64 lines
3.3 KiB
Markdown
64 lines
3.3 KiB
Markdown
# 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**
|