Skip to main content

sdac-search-analysis-evidence

Purpose​

Searches normalized SDAC analysis evidence persisted by the report-analysis workflow and comparison tools. This is the Coordinator Release Agent's preferred broad retrieval surface for review summaries, send-back questions, row-level findings, validation decisions, historical evidence, and cross-quarter analysis.

Tool type​

Database retrieval with optional on-demand comparison generation

Tool ID​

sdac-search-analysis-evidence

Inputs​

  • report_id (string, optional) -- Current cost report identifier.
  • district_sk (number, optional) -- Internal district surrogate key.
  • external_district_id (string, optional) -- External or TherapyLog district identifier.
  • district_name (string, optional) -- District name search text.
  • year (number, optional) -- Report year filter.
  • quarter (string, optional) -- Quarter filter, such as Q1.
  • analysis_types (string[], optional) -- Analysis types to retrieve.
  • scope_types (REPORT | COMPARISON | TREND | DISTRICT_PERIOD_SEARCH[], optional).
  • query (string, optional) -- Reserved for future ranking.
  • include_raw (boolean, optional, default: false) -- Includes raw result JSON.
  • include_findings (boolean, optional, default: true) -- Includes normalized finding rows.
  • for_conversation (boolean, optional, default: true) -- Applies conversational visibility filtering.
  • generate_if_missing (boolean, optional, default: false) -- Generates supported missing comparison evidence on demand.
  • limit (number, optional, default: 10) -- Maximum evidence rows to return.

Outputs​

  • success
  • status (available | partial | started | not_found | error)
  • evidence -- Matching evidence rows with summaries and optional findings.
  • missing -- Requested analysis types/scopes that were not found.
  • started -- Comparison evidence generation tasks started by the call.
  • summary
  • execution_time_ms

Example output​

{
  "success": true,
  "status": "available",
  "evidence": [
    {
      "evidence_id": 9912,
      "analysis_type": "FRINGE",
      "scope_type": "REPORT",
      "scope_key": "REPORT:SDAC-2024-Q2-001",
      "status": "completed",
      "visibility_status": "visible",
      "passed": false,
      "error_count": 1,
      "warning_count": 2,
      "records_checked": 84,
      "finding_count": 3,
      "summary": "Fringe validation: needs review, 1 error(s), 2 warning(s).",
      "findings": [
        {
          "finding_id": 12004,
          "rule_id": "FRINGE_WITH_ZERO_SALARY",
          "severity": "ERROR",
          "release_blocking": true,
          "row_number": 48,
          "record_id": 4801,
          "first_name": "Taylor",
          "last_name": "Jones",
          "job_title": "Speech Language Pathologist",
          "cost_pool": "1",
          "message": "Fringe is claimed for a position with $0 claimable salary.",
          "current_value": "4200",
          "expected_value": "0",
          "suggested_correction": "Remove the fringe claim or provide corrected salary attribution."
        }
      ],
      "result": null
    }
  ],
  "missing": [],
  "started": [],
  "summary": "Found 1 evidence row(s).",
  "execution_time_ms": 23
}

Functional details​

  • Searches SDAC.analysis_Evidence by report, district, period, analysis type, and scope type.
  • Retrieves normalized row-level findings from SDAC.analysis_Findings when include_findings is true.
  • Applies feature-flag visibility filtering for conversational use.
  • Can generate supported missing comparison evidence by calling sdac-compare-multiple-quarters when generate_if_missing=true.
  • Returns hidden or disabled analysis sections as absent evidence rather than exposing internal feature-flag state to the user.

Implementation details​

  • Uses searchEvidence() and getEvidenceFindings() from packages/domain-sdac/src/evidence/evidence-store.ts.
  • Persists generated comparison outputs through persistComparisonEvidence().
  • The Coordinator Release Agent should call this before raw validation tools for broad review, send-back, validation decision, row-level, and historical questions.

Code Location: packages/domain-sdac/src/tools/search-analysis-evidence.tool.ts