Skip to content
sacs.ai

Build an interim projection with SACS.ai

Start here when the user asks to build, create, or match a projection. Do not say creation is unavailable merely because there is no Excel-upload tool. The client reads attached Excel/DAT files; SACS stores and validates the resulting account-level scenario. Discover the actual tools and key scope first.

Choose the source correctly

Suggested flow

  1. Call sacs_list_organizations and inspect the relevant organization/entitlement. Check the advertised tool list. Creation/editing uses the existing Read + edit datasets/projections key; read-only keys can inspect and read this guide. Do not ask for a new key when the current key already supports writes.
  2. Establish district CDS, fiscal year, first/second/third interim, fund/resource scope, signs, workbook sheets and columns, YTD as-of date and known balances. First-interim projected year-end totals normally target I1/IP; I1/IA is a different basis. Do not invent opening balances or treat missing amounts as zero. Preserve legitimate negative adjustments and project-year digits.
  3. Read the supplied spreadsheet/YTD files locally in the client. Separate historical actuals, adopted/revised budget, YTD, current-year projected totals and future MYP years. Build a reconciliation table of workbook forecast totals and assumptions by fund/object group. Record units, source sheet/cells and whether assumptions are already embedded. Avoid applying an embedded salary/benefit increase twice.
  4. Use public tools on this same premium connection for district identity, official filing context, code definitions and CSAM citations. Discover explicit official dataset references; keep periods/columns separate. Public summary tools do not supply a complete private account ledger, and partial historical coverage is not zero activity.
  5. Map the summary forecast to full SACS accounts using the provided detail or an agreed baseline/allocation. Preserve known fund/resource/goal/function/project-year distributions. Do not invent splits or spread restricted resources indiscriminately. Reconcile every fund/object group to the workbook target and compare forecast versus YTD; explain apparent forecast-below-YTD differences rather than silently flooring them.
  6. Create the scenario: either sacs_fork_projection from a pinned uploaded forecast/budget, or sacs_create_projection from prepared [account, amount] pairs. Creation requires exact decimal cents, source_basis=projected_year_end, a source_description recording the workbook/YTD/assumptions/allocation method, explicit target basis, and matching control_totals for every represented fund/object group. Accounts concatenate fund(2), resource(4), project-year(1), goal(4), function(4), object(4). Never put an API key in arguments. The service validates catalog codes and control totals; it does not certify the forecast assumptions.
  7. Inspect the returned scenario with sacs_inspect_projection using the returned revision, fund=all and include_rows=false. Reconcile the saved statement against the workbook and explain scope, remaining unmapped amounts and assumptions. For current-year Fund 01 presentation use sacs_current_year_projection. Missing opening/ending balances remain unknown. A saved draft is not proof that the account mapping is complete.
  8. For changes use sacs_preview_projection (a complete ordered plan, replayed from the immutable base) or sacs_preview_projection_dartboard. Include context for each assumption and accurate expect_matches. Inspect diffs and reconcile totals; preserve existing ordinary steps. Commit the exact preview ID/hash with expected_revision and a UUID idempotency_key. Reuse that key only for retrying the identical request. Do not add a dartboard on top of workbook assumptions already embedded in the forecast.
  9. Use sacs_review_projection and balance diagnostics on the pinned revision. Submit sacs_submit_projection_trc for that exact revision and poll sacs_get_analysis_job; do not resubmit merely because compute is delayed. Fix fatal failures in a new reviewed revision, rerun TRC, and have the analyst decide reported warnings. Source-dataset TRC does not authorize projection export.
  10. Export through sacs_export_projection_dat after the exact-revision check. Concatenate pages unchanged, verify a stable file_hash, preserve signs and project-year digits, and reconcile the real SACS Web import and its validation. The migrated TRC catalog is partial; do not claim full CDE certification. Preserve 979Z as calculated ending balance, never relabel it as opening 9791.

Example prepared account input

For a synthetic district whose codes have been resolved, two forecast accounts might be:

accounts: [["0100000111021001100", "100000.00"], ["0100000111021008980", "5000.00"]]
control_totals: [{"fund":"01","object_group":"1000","amount":"100000.00"}, {"fund":"01","object_group":"8000","amount":"5000.00"}]

Amounts here are illustrative. The totals are account sums, not a surplus or a calculated fund balance. Do not copy these codes or amounts into a real forecast without the user's actual mapping. Duplicate accounts must be explicitly aggregated before creation. The current limits are 5,000 rows, 256 KiB per request and 50 scenarios per organization; larger/unmapped work needs a concrete supported handoff, not silent truncation.

MYP and client limitations

The saved engine currently models one target fiscal year per scenario. Read the workbook's future-year assumptions and retain them in the working reconciliation; do not present one current-year scenario as a complete multi-year engine. Create separately justified annual scenarios when account-level forecasts exist; no automatic year roll-forward is implied. The MCP service does not open files from Claude's local filesystem or fetch arbitrary private URLs. If a workbook is unreadable, a scope lacks writes or an allocation is unresolved, report the exact blocker and what has already been prepared rather than saying no projection tooling exists.