Skip to main content

SDAC Tools

Overview​

SDAC tools are organized by validation category and workflow stage. Each tool is focused and short-lived, which keeps individual docs manageable while still covering the full SDAC review process.

Most tools operate on a report_id and read from SDAC.data_* tables.

AI vs deterministic tools​

Deterministic (rule-based) tools produce consistent results given the same inputs:

AI-assisted tools use a language model and may vary slightly across runs:

Upload & registration​

Core validation​

Review & compliance checks​

Helper tools​

Analysis & orchestration​

Communication​

Data ingestion​

  • sdac-fetch-costs -- Syncs SDAC cost data from TherapyLog via the Ingestion Server

Report context​

Feedback​

Session management​

These tools manage AI Widget conversation state (stored in SDAC.fact_ConversationHistory):

Note: The direct runtime POST /sdac/chat route handles session management automatically. Widget browser code calls it through /api/ingestion/sdac/chat. These tools are available for custom integrations.

AI-assisted review tools​

These tool IDs use the standard sdac- prefix. Use the exact tool ID when invoking them.

Where these tools live​

  • TypeScript tools: packages/domain-sdac/src/tools/
  • Tool registry: sdacTools in packages/domain-sdac/src/tools/index.ts

Parallel Validation​

Validate multiple categories simultaneously for speed:

const [sourceResult, functionResult, costPoolResult] = await Promise.all([
  validateSourceCodesTool.execute({ report_id }),
  validateFunctionCodesTool.execute({ report_id }),
  validateCostPoolsTool.execute({ report_id })
]);

Comprehensive Validation​

Single call for complete validation:

const fullResult = await validateFullReportTool.execute({
  report_id: "Q1-2024-District123",
  complexity: "VERY_COMPLEX",
  include_statistical_analysis: true
});

// Returns comprehensive report with all categories
console.log(`Total errors: ${fullResult.total_errors}`);
console.log(`Errors by category:`, fullResult.errors_by_category);

Error Explanation Flow​

Explain specific validation failures:

// 1. Run validation
const result = await validateSourceCodesTool.execute({ report_id });

// 2. If errors found, explain them
for (const error of result.errors) {
  const explanation = await explainValidationErrorTool.execute({
    rule_id: error.rule_id,
    record_id: error.record_id,
    report_id: report_id
  });

  console.log(`Error: ${error.message}`);
  console.log(`Explanation: ${explanation.explanation}`);
  console.log(`How to fix:`, explanation.correction_steps);
}

Common Validation Scenarios​

New Report Upload and Validation​

// 1. Upload new report
const uploadResult = await uploadCostReportTool.execute({
  file_path: "C:\\Reports\\District123_Q1.xlsx",
  district_id: "District123",
  quarter: "Q1-2024"
});

const reportId = uploadResult.report_id;  // "Q1-2024-District123"

// 2. Run comprehensive validation
const validationResult = await validateFullReportTool.execute({
  report_id: reportId,
  complexity: "VERY_COMPLEX"
});

// 3. Review results
if (!validationResult.passed) {
  console.log(`Found ${validationResult.total_errors} errors`);
  console.log('Errors by category:', validationResult.errors_by_category);
}

Focused Category Validation​

// Validate only source codes for quick check
const sourceResult = await validateSourceCodesTool.execute({
  report_id: "Q1-2024-District123"
});

if (sourceResult.error_count > 0) {
  // Fix source code errors before continuing
  console.log('Please fix source code errors first:');
  sourceResult.errors.forEach(err => {
    console.log(`- Row ${err.row_number}: ${err.message}`);
  });
}

Duplicate Detection​

// Check for suspicious duplicate values
const dupResult = await detectDuplicatesTool.execute({
  report_id: "Q1-2024-District123",
  field: "both",  // Check salary AND fringe
  consecutive_only: true,
  min_occurrences: 3  // 3+ consecutive duplicates
});

if (dupResult.total_duplicate_groups > 0) {
  console.log('Potential data entry errors detected:');
  dupResult.duplicates_found.forEach(dup => {
    console.log(`- Rows ${dup.row_numbers}: ${dup.value} appears ${dup.occurrences} times`);
  });
}

Tool Reference Summary​

CategoryToolsStatus
Deterministic validation26Implemented in TypeScript
AI-assisted analysis5LLM-backed analysis
Analysis & orchestration5Persisted report-analysis workflow tools plus legacy orchestration
Data ingestion1TherapyLog sync via Ingestion Server
Report context1Report metadata lookup
Feedback2User feedback capture and analysis
Session management3Conversation history

Total: See packages/domain-sdac/src/tools.ts for the authoritative exported tool list.

Next Steps​

SDAC Agents

Learn how agents use these tools

SDAC Workflows

See end-to-end validation workflows

SDAC Introduction

Back to SDAC overview