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
- Complete projected account ledger already uploaded to the organization: list datasets, query the selected dataset, pin revision/content_hash, then use sacs_fork_projection.
- Excel contains a summary/MYP and assumptions: read the workbook in your client, identify the current-year forecast column, and prepare an explicit account mapping/allocation before using sacs_create_projection. That tool accepts prepared full-year account totals; it does not parse an arbitrary workbook or decide allocations for you.
- A YTD extract is actual activity through its stated as-of date. Keep it separate from the full-year forecast. It can supply account structure and reconciliation evidence; do not relabel its amounts as I1/IP projected totals or annualize every account mechanically.
- An adopted/revised budget or prior forecast is a useful allocation baseline, not a mandatory substitute for the user's workbook. If missing account detail prevents a supported allocation, explain the specific missing mapping and ask for that baseline or the user's allocation choice. Continue extracting assumptions, checking totals and preparing the draft meanwhile.
Suggested flow
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.