# _config_schema

URL: /pounce/api/_config_schema/
Section: api
Description: ServerConfig introspection — JSON Schema export and redacted view.

Two entry points, both consumed by the ``pounce config`` subcommands:

- `build_schema`() / `build_toml_template`() — emit a JSON Schema
  (Draft 2020-12) or commented ``pounce.toml`` template from the
  `ServerConfig` dataclass. Enables agents and humans
  to discover the config surface without reading source.
- `redacted_config_view`() + `INFO_ALLOWLIST` — produce the
  fail-closed redacted view used by ``pounce config show`` and the Sprint 4
  ``/_pounce/info`` endpoint. Every field must appear in the allowlist;
  absent fields are implicitly redacted.

Design notes:

- No new runtime dependencies. Stdlib-only (``dataclasses``, ``typing``,
  ``json``).
- Deterministic output: properties are emitted in sorted order so golden
  snapshots remain stable.
- Internal / callable / opaque fields (the ``_IIC_SKIP_FIELDS`` set in
  ``config.py``) are skipped in both schema and redacted view.

---

> For a complete page index, fetch /pounce/llms.txt.

Open LLM text
(/pounce/api/_config_schema/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_config_schema%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_config_schema%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_config_schema%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_config_schema%2Findex.txt)

Module

#
`_config_schema`

ServerConfig introspection — JSON Schema export and redacted view.

Two entry points, both consumed by the`pounce config`subcommands:

- `build_schema`() / `build_toml_template`() — emit a JSON Schema
(Draft 2020-12) or commented`pounce.toml`template from the
`ServerConfig`dataclass. Enables agents and humans
to discover the config surface without reading source.

- `redacted_config_view`() + `INFO_ALLOWLIST`— produce the
fail-closed redacted view used by`pounce config show`and the Sprint 4
`/_pounce/info`endpoint. Every field must appear in the allowlist;
absent fields are implicitly redacted.

Design notes:

- No new runtime dependencies. Stdlib-only (`dataclasses`, `typing`,
`json`).

- Deterministic output: properties are emitted in sorted order so golden
snapshots remain stable.

- Internal / callable / opaque fields (the`_IIC_SKIP_FIELDS`set in
`config.py`) are skipped in both schema and redacted view.

11Functions

## Functions

`_field_stability`

1

`str`

▼

Return the stability tier (``"stable"`` or ``"beta"``) for *name*.

`def _field_stability(name: str) -> str`

##### Parameters

Name
Type
Description

`name`
`str`

##### Returns

`str`

`_strip_none`

1

`tuple[Any, bool]`

▼

For ``X | None``, return ``(X, True)``. Else ``(tp, False)``.

`def _strip_none(tp: Any) -> tuple[Any, bool]`

##### Parameters

Name
Type
Description

`tp`
`Any`

##### Returns

`tuple[Any, bool]`

`_map_type`

1

`dict[str, Any] | None`

▼

Return a JSON Schema fragment for *tp*, or None to drop the field.

`def _map_type(tp: Any) -> dict[str, Any] | None`

##### Parameters

Name
Type
Description

`tp`
`Any`

##### Returns

`dict[str, Any] | None`

`_collect_enum_fields`

1

`dict[str, frozenset[str]]`

▼

Harvest enum constraints from ``_VALID_S`` dataclass fields.

``_VALID_LOG_LEVE…

`def _collect_enum_fields(cls: type) -> dict[str, frozenset[str]]`

Harvest enum constraints from`_VALID_<NAME>S`dataclass fields.

`_VALID_LOG_LEVELS` (/pounce/api/config/#ServerConfig) → `log_level`.

##### Parameters

Name
Type
Description

`cls`
`type`

##### Returns

`dict[str, frozenset[str]]`

`build_schema`

1

`dict[str, Any]`

▼

Build a JSON Schema Draft 2020-12 document for a dataclass.

The schema is dete…

`def build_schema(cls: type = ServerConfig) -> dict[str, Any]`

Build a JSON Schema Draft 2020-12 document for a dataclass.

The schema is deterministic: properties are sorted alphabetically so
golden-snapshot tests stay stable across runs.

##### Parameters

Name
Type
Description

`cls`
`type`

Default:`ServerConfig`

##### Returns

`dict[str, Any]`

`_toml_value`

1

`str`

▼

Render a Python default as a TOML literal.

`def _toml_value(v: Any) -> str`

##### Parameters

Name
Type
Description

`v`
`Any`

##### Returns

`str`

`build_toml_template`

1

`str`

▼

Emit a commented TOML template for *cls*, one field per line.

``pounce.toml`` …

`def build_toml_template(cls: type = ServerConfig) -> str`

Emit a commented TOML template for cls, one field per line.

`pounce.toml`puts config keys at the top level (no section header) —
the loader in`_config_file.py`treats the whole file as config.
Users who want`[tool.pounce]`for pyproject.toml can copy the same
commented lines under that heading.

##### Parameters

Name
Type
Description

`cls`
`type`

Default:`ServerConfig`

##### Returns

`str`

`_is_set`

1

`bool`

▼

Interpret ``REDACT_TO_BOOL`` — True when the field has a meaningful value.

`def _is_set(value: Any) -> bool`

##### Parameters

Name
Type
Description

`value`
`Any`

##### Returns

`bool`

`redacted_config_view`

1

`dict[str, Any]`

▼

Return a redacted dict view of *cfg* suitable for ``/info`` or ``config show``.…

`def redacted_config_view(cfg: ServerConfig) -> dict[str, Any]`

Return a redacted dict view of cfg suitable for`/info` or `config show`.

EXPOSE fields keep their values; REDACT_TO_BOOL fields become
`<field>_set: bool`; every other field is omitted entirely.

##### Parameters

Name
Type
Description

`cfg`
`ServerConfig (/pounce/api/config/#ServerConfig)`

##### Returns

`dict[str, Any]`

`_coerce_for_json`

1

`Any`

▼

Coerce a ServerConfig value into JSON-serializable form.

`def _coerce_for_json(value: Any) -> Any`

##### Parameters

Name
Type
Description

`value`
`Any`

##### Returns

`Any`

`assert_allowlist_covers_config`

0

`list[str]`

▼

Return a list of ServerConfig fields missing from INFO_ALLOWLIST.

Used by ``te…

`def assert_allowlist_covers_config() -> list[str]`

Return a list of ServerConfig fields missing from INFO_ALLOWLIST.

Used by`tests/unit/test_config_schema.py`to guarantee that adding a
new field to ServerConfig without updating the allowlist fails CI.

##### Returns

`list[str]`