Skip to content

refactor(api): consolidate duplicate base/Enhanced request schemas (ChatMessage, SearchRequest, GoalPayload, ChatHealthData) #10654

Closed

Description

@mrveiss

Consolidate duplicate base/Enhanced API request schemas (from #10627 py-duplicate-concept)

Surfaced by the py-duplicate-concept warn rule (umbrella #10569 / #10577). Four api/schemas_*.py pairs are a base model coexisting with an Enhanced* variant of the same concept — the canonical-drift the umbrella targets, but in public API schemas, so consolidation needs migration + contract review (not a lint waiver).

Pairs (verified field analysis on Dev_new_gui)

  1. ChatMessage (schemas_chat.py:461) vs EnhancedChatMessage (:520) — Enhanced is a strict superset: base fields (content,role,session_id,message_type,metadata,language) + use_ai_stack,use_knowledge_base,response_style,include_sources,thinking_mode_enabled. 11 prod usages of Enhanced.
  2. SearchRequest (schemas_knowledge.py:1024) vs EnhancedSearchRequest (:1040) — Enhanced superset: base (query,limit,category) + offset,tags,tags_match_any,mode,enable_reranking,min_score,access-level. 5 usages.
  3. GoalPayload (schemas_agent.py:1555) vs EnhancedGoalPayload (:1567) — same concept (submit a goal), divergent fields (base: use_phi2,user_role; enhanced: agents,coordination_mode,priority,context,use_knowledge_base,include_reasoning). 2 usages. Needs field reconciliation.
  4. ChatHealthData (schemas_chat.py:217) vs EnhancedChatHealthData (:272) — base + enhanced health payload. 2 usages.

NOT a duplicate (waive in the rule, do not consolidate)

  • UnifiedSearchRequest (schemas_knowledge.py:4564) — a different concept: multi-source search across facts/relations/documentation with graph expansion (top_k,doc_results,expand_relations,score_threshold,include_sources). "Unified" = unified-across-sources, a legitimate domain term, NOT a v2 of SearchRequest. Add # canonical: ignore py-duplicate-concept with this reason.

What to do (per pair, careful — public API contracts)

  • Decide the canonical shape (usually the Enhanced superset becomes the one model; the base becomes an alias or is folded). Migrate all endpoint handlers + any frontend/client types. Preserve request/response field contracts (OpenAPI schema names may change — coordinate).
  • Where a base is still needed for a minimal endpoint, keep it but rename the variant to a descriptive non-Enhanced name (e.g. RankedSearchRequest) so it's not a "v2 of" smell.
  • Each pair can be its own PR. Once all four are resolved + UnifiedSearchRequest waived, promote py-duplicate-concept warn→block.

Note

py-duplicate-concept is intentionally a warn heuristic (#10577) — it stays warn until this lands. The other 4 umbrella rules (sync-requests, hardcoded-url, banned-suffix, adhoc-db) are now BLOCK.

Activity

  1. mrveiss commented on Jun 29, 2026

    @mrveiss
    OwnerAuthor

    Done — folded into umbrella #10666 (canonical-naming). The duplicate API schemas are consolidated into single canonical classes, no prefixed names or aliases left:

    git grep for these prefixed schema names = 0. Closing; the broader prefix sweep continues under #10666.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions