Skip to main content

SDAC Validation System

Overview​

SDAC (School District Administrative Claims) validation provides a developer-friendly toolset for reviewing Medi-Cal Administrative Activities (MAA) cost reports. The system is designed for iterative validation: ingest a report once, run targeted checks many times, and generate clear correction guidance.

Architecture at a glance​

  • Tools: category-based validation, helper, and AI-assisted analysis tools.
  • Agents: 11 specialized review, widget, evaluation, and feedback-planning agents backed by database-managed prompts with version tracking.
  • Workflows: Seven registered pipelines for report analysis, release review, widget sessions/conversations, feedback aggregation, prompt tuning, and Linear automation.
  • AI Widget: Real-time streaming chat interface for auditors via the Coordinator Release Agent.

Tooling overview​

SDAC tools are organized into short, focused units so each page stays easy to maintain:

  • Upload & registration: sdac-upload-cost-report ties a processed report to a report_id.
  • Core validation: Source codes, function codes, cost pools, salaries, fringe, replacements.
  • Compliance checks: Federal backouts, indirect cost functions, vacant positions, quarter comparisons, justifications.
  • Explainers & AI assist: Error explanation plus LLM-assisted review helpers.

See SDAC Tools for the complete, per-tool catalog.

Developer flow (typical)​

  1. Register the report → call sdac-upload-cost-report with a known report_id.
  2. Validate → run category tools or sdac-validate-full-report.
  3. Explain → use sdac-explain-validation-error or the explainer assistant.
  4. Compare → use sdac-compare-quarters + sdac-validate-justifications when reviewing deltas.
  5. Sendback → produce response text with sdac-generate-sendback-summary.

Key concepts​

  • report_id is the anchor: most tools operate against database rows for a single report.
  • Category tools, not rule tools: one tool executes all rules in a category for predictable workflows.
  • Iterative validation: fix data, re-run tools, and track improvements without re-ingesting.

Next steps​

SDAC Tools

Full catalog of validation and analysis tools

SDAC Agents

11 specialized agents with prompt IDs and capabilities

SDAC Workflows

Validation flows and prompt tuning pipeline

Modular Tool Architecture​

Category-based tools (NOT one tool per rule):

  • One tool validates multiple related rules
  • Example: sdac-validate-salaries executes 6 salary rules
  • More efficient: 7 tool calls instead of 30+ individual rule calls

Profile-Based Agent Management​

Agents use database-managed prompts:

  • Prompts editable via Admin UI
  • Version tracking with ProfileHash
  • Per-profile LLM model overrides

Workflow Example​

Upload, Validate, Explain​

// 1. User uploads file
User: "I have District123_Q1.xlsx at C:\Reports\..."

// 2. Agent uploads file
Agent calls: sdac-upload-cost-report
Returns: { report_id: "Q1-2024-District123", total_records: 375 }

// 3. User requests validation
User: "Validate the source codes"

// 4. Agent validates
Agent calls: sdac-validate-source-codes { report_id: "Q1-2024-District123" }
Returns: { errors: 3, warnings: 2, ... }

// 5. Agent explains errors
Agent: "I found 3 errors:
- Row 15: Invalid source code '5' (must be 0-4)
- Row 28: Source 4 with claimable amount (should be $0)
- Row 42: Format error '1 2' should be '1,2'"

// 6. User asks for details
User: "Why is row 28 an error?"

// 7. Agent explains
Agent calls: sdac-explain-validation-error
Provides: Detailed explanation with SDAC guideline references