feat(filter_runtime): typed FilterConfigBase + emit_schema (FILTER-441)

[stwilt]

📦 Pull Request

📋 What does this PR do?

Introduces FilterConfigBase(BaseSettings) — the typed, introspectable successor to the legacy adict-based FilterConfig — and the surrounding machinery that lets a filter declare its config contract in Python and emit it as a JSON Schema (draft 2020-12) the platform can ingest without pulling the filter image.

Specifically:

• New FilterConfigBase in openfilter/filter_runtime/config.py. Subclasses get pydantic-settings env-var sourcing (FILTER_* prefix, __ nested delimiter), declarative range/enum/pattern/format constraints, and a model_json_schema() export.
• New openfilter/filter_runtime/formats.py — OpenfilterSource and VideoSource Annotated aliases plus their Python-side validators (FC-1.5 py).
• FC-2 markers: x-openfilter-managed, x-openfilter-resolve, and x-openfilter-preflight JSON Schema extension keywords, plus Managed(...) and Resolve(...) field helpers. Managed fields are stripped from the operator-facing schema by default (filter exposes operator surface only; orchestrator handles managed fields).
• New authoring guide at docs/declarative-config.md covering the typed-config contract end to end (Tier 1/2/3 migration, env-var sourcing, tagged unions, named formats, the Managed / Resolve boundary).
• Tier-3 fallback intact: filters that don't subclass FilterConfigBase keep working unchanged.
• Adds pydantic~=2.9 and pydantic-settings~=2.6 as hard deps; lock file refreshed.

The build-time CLI half (openfilter emit-schema) is stacked on top of this PR as
FILTER-442.

---

🔍 Why is this needed?

Filter authors need a way to declare their config contract once, in Python, and have the platform pick it up at deploy time without side-loading filter images. Today the platform infers config from hand-maintained env-var docs that drift; the platform-side ingest work (Declarative Configuration Validation) is blocked on having a real schema artifact to ingest.

This PR is the SDK-side scaffolding for that contract. It ships the typed base class, the named-format aliases, and the FC-2 boundary markers that distinguish operator-visible config from platform-managed / resolved / preflight fields. Once it lands, individual filters can opt in at their own cadence (Tier 1/2 per the design doc); unmigrated filters keep working through the openfilter 1.0 cut.

Design doc:
Declarative Filter Configuration Contract — Goldenrod.2.

---

🧪 How was it tested?

Unit tests (37, all passing)

tests/test_filter_config_base.py covers:

• env-var sourcing with the FILTER_* prefix
• tagged unions via env_nested_delimiter="__" (sam3 prompt-mode fitness test)
• managed-field exclusion in emit_schema() and --include-managed parity
• Managed / Resolve field helpers and parent/child override semantics
• OpenfilterSource / VideoSource validators (accept/reject + JSON Schema format keyword)

$ uv run --with pytest pytest tests/test_filter_config_base.py -q
.....................................                                    [100%]
37 passed in 0.30s

Integration spike: sam3-shaped config

Validated FILTER-441's load-bearing acceptance criterion — sam3's three mutually-exclusive prompt modes as a tagged union — against a sam3-shaped FilterConfigBase subclass (text / multi-text / exemplars prompt modes, plus Managed sources and device fields, plus representative hyperparams). Results:

• ✅ prompting emits a discriminated union with discriminator: {propertyName: "prompt_mode", mapping: {...}} and oneOf referring to $defs/{TextPrompt,MultiTextPrompt,Exemplars}
• ✅ Managed fields (sources, device) stripped from operator-facing schema; --include-managed surfaces them with x-openfilter-managed and x-openfilter-resolve markers
• ✅ sources.items.format == "video-source" (FC-1.5 named format round-trips)
• ✅ Pydantic-settings env-var sourcing into the tagged union: FILTER_PROMPTING__PROMPT_MODE=text FILTER_PROMPTING__TEXT_PROMPT='person walking' parses into the TextPrompt variant; FILTER_CONFIDENCE_THRESHOLD=0.7 overrides the top-level default
• ✅ Top-level required: ["prompting"] correctly surfaces fields with no default

This stacks on FILTER-442 for the CLI invocation; the spike was run via
python -m openfilter.cli emit-schema from the FILTER-442 worktree.

Tier-3 fallback

No production filter touched in this PR. Filters that don't subclass FilterConfigBase (i.e. every existing one) are unaffected.

---

🔗 Related Issues

• FILTER-441 — this ticket
• FILTER-440 — Declarative Configuration Contract (parent epic)
• FILTER-442 — openfilter emit-schema CLI (stacked, follows this PR)

---

🖼️ Screenshots or Logs (if applicable)

Sample emitted schema (managed field stripped by default):

class MyFilter(FilterConfigBase):
    sources: list[VideoSource] = Managed([], resolve="orchestrator-generated")
    confidence_threshold: float = Field(default=0.5, ge=0, le=1)

>>> MyFilter.emit_schema()
{
  "title": "MyFilter",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "confidence_threshold": {
      "type": "number", "minimum": 0, "maximum": 1, "default": 0.5
    }
  },
  ...
}

---

✅ Checklist

• I have read and agreed to the terms of the LICENSE
• I have read the CONTRIBUTING guide
• I have followed the coding style
• I have signed all commits in compliance with the DCO (git commit -s)
• I have added or updated tests as needed
• I have added or updated documentation as needed (docs/declarative-config.md — authoring guide for the typed-config contract; the parent epic FC-12 row is closed by this addition)

[lucasmundim]

Solid PR — the design cleanly separates operator-facing from platform-managed config, the pydantic-settings integration is well done, and the 37 tests cover the core contracts well. The _NamedFormat pattern for injecting format: into JSON Schema while keeping the runtime validator is elegant, and the authoring guide is thorough.

A few items worth addressing before merge:

[lucasmundim]

Second-pass review. All first-round items confirmed fixed in b0175e7. The PR is in good shape — none of these are blockers, mostly suggestions and edge-case hardening.

[lucasmundim]

Round-3 review — all round-2 items verified in d724eb5:

• typing-extensions floor relaxed to >=4.6 to match pydantic
• required: [] omitted when every required field is managed (top-level and nested); new required_handled flag handles dict-iteration order both ways
• $schema: "https://json-schema.org/draft/2020-12/schema" injected in emit_schema() via setdefault
• ResolveHint added to __all__ and re-exported from openfilter.filter_runtime
• json_schema_extra merge behavior locked in by test

The new @deprecated decorator on legacy FilterConfig is well-scoped — verified third-party subclassers still see the warning under python -W error::DeprecationWarning, and openfilter-internal ones are correctly silenced via the module-name regex. The append=False choice is deliberate and well-commented.

46/46 tests in test_filter_config_base.py pass.