linyuhang
/
PMFlow
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
PMFlow/docs/superpowers/plans/2026-04-15-external-query-g...

3.3 KiB
Raw Blame History

External Query Gateway Baseline Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Route non-plan external query.answer through a dedicated external gateway, keep DuckDuckGo HTML search as bounded fallback, and stop internal sources from leaking into external answers.

Architecture: Add a small external_query_service that owns structured planning, adapter selection, and external evidence verification. Wire AdaptiveRAG external probing and retrieval to that service so route_mode=external no longer answers from internal retrieval or fail-open source summaries.

Tech Stack: Python 3.11, FastAPI, PMFlow AdaptiveRAG, Pydantic, pytest, httpx

Task 1: Lock The External Gateway Contract With Tests

Files:

  • Modify: backend/tests/test_adaptive_rag_mainline_contract.py

  • Step 1: Write failing tests for external gateway fallback order

  • Step 2: Write failing tests for external source filtering to fail closed

  • Step 3: Run targeted pytest to confirm the new tests fail for the right reason

Task 2: Add External Query Service And Planner Contract

Files:

  • Create: backend/app/services/external_query_service/__init__.py

  • Create: backend/app/services/external_query_service/schemas.py

  • Create: backend/app/services/external_query_service/planner.py

  • Create: backend/app/services/external_query_service/registry.py

  • Create: backend/app/services/external_query_service/gateway.py

  • Create: backend/app/services/external_query_service/adapters/live_search.py

  • Create: backend/app/services/external_query_service/adapters/mcp.py

  • Modify: backend/app/config/ai_prompts.py

  • Modify: backend/app/services/llm_service/shared_part_01.py

  • Step 1: Add structured ExternalQueryPlan / evidence schemas

  • Step 2: Add planner prompt and structured schema registration

  • Step 3: Implement registry-first gateway with MCP placeholder and live-search fallback

  • Step 4: Re-run targeted pytest for the service layer

Task 3: Wire AdaptiveRAG External Probe And Retrieval

Files:

  • Modify: backend/app/services/adaptive_rag_service/mixin_answer_retrieval.py

  • Modify: backend/app/services/adaptive_rag_service/mixin_query_route_gateway.py

  • Modify: backend/app/services/adaptive_rag_service/mixin_deep_guard_rules.py

  • Step 1: Route external probe through the new gateway

  • Step 2: Route external retrieval through the new gateway instead of direct HTML search

  • Step 3: Add external answer verification / guard behavior

  • Step 4: Re-run targeted pytest for AdaptiveRAG contracts

Task 4: Update Docs And Verify

Files:

  • Modify: CLAUDE.md

  • Modify: docs/architecture/ARCHITECTURE_INVENTORY.md

  • Modify: docs/architecture/CODE_REFERENCE_INDEX.md

  • Modify: docs/architecture/RUNTIME_GUARDRAILS.md

  • Step 1: Update architecture/runtime docs for the external gateway chain

  • Step 2: Run targeted backend pytest

  • Step 3: Run python -m py_compile on touched backend modules

  • Step 4: Summarize MCP adapter assumptions and current fallback behavior