| title | Documentation Index |
|---|---|
| slug | readme |
| type | index |
| status | canonical |
| created | 2026-04-07 |
| updated | 2026-06-05 |
| owner | Team 13 |
| scope | team-repo |
| canonical | true |
Living, authored documentation for the SmartGridBench project. Everything in this directory is a doc that evolves with the project - domain background, setup guides, architecture notes, methodology. Historical planning records live in ../planning/archive/; current task truth lives in GitHub Issues / Projects and active docs. Frozen deliverables (shipped PDFs, slide decks) live in ../reports/. Historical supporting notes that are no longer live move into archive/. Lower-churn class / mentor / setup references now live under knowledge-base/reference/. Durable closeouts and extracted lessons live under retrospectives/ and knowledge-base/.
| File | Purpose | Start here if… |
|---|---|---|
| project_synopsis.md | Cold-start project overview with full domain background, problem statement, team roles, timeline, current status | You're new to the project and want the complete picture in ~10 minutes |
| knowledge-base/reference/2026-04-05_project_reference.md | Class requirements, grading rubric, mentor guidance, course context, report templates | You need to know what HPML class/Dhaval expects as deliverables |
| execution_plan.md | Task dependency map (Tier 1-5 critical path) + benchmarking operations (async batch workflow, 5-cell experimental grid, role clarifications) | You want to know what blocks what, who owns what, and what running experiments actually looks like operationally |
| runbook.md | Canonical end-to-end reproducibility runbook for the infra side — preconditions, first-time setup, submitting benchmark cells, profiling workflow, troubleshooting decision tree, pointers to detailed runbooks | You need to stand up the serving / benchmark / profiling pipeline from scratch without verbal help |
| infra_profiling_serving_brief.md | One-page paper-bound fact pack for #43: model IDs + version pins + Slurm run shape + profiling instrumentation + WandB linkage + canonical run IDs + GCP A100 path + known limitations. Verbatim-quotable bullets, no narrative |
You're filling §3 System Design or the §infra paragraphs of #39 / #40 and need concrete cite-by-job-id facts without rereading every detailed runbook |
| validation_log.md | Canonical log of concrete serve / benchmark / profiling proofs, including run IDs, artifacts, what each run actually proved, and caveats | You need the durable record of live validation runs rather than the how-to runbooks |
| compute_plan.md | Phase-by-phase GPU allocation across Insomnia (H100, A6000) and $500/person GCP budget, hardware strategy decisions | You need to spin up an environment or pick a GPU for a workload |
| gcp_fallback.md | Emergency GCP A100 spin-up runbook — when to use it, instance selection, env setup, artifact persistence, shutdown, spot preemption handling, budget tracking, known GPU differences from Insomnia | Insomnia is down / queue-saturated and you need GPUs now, or you're considering a one-off A100 run |
| insomnia_runbook.md | Verified Insomnia setup notes - Slurm account/partition/QoS, scratch storage, CUDA/cuDNN workarounds, vLLM Python-version gotcha, login-node etiquette, queue tips, foreground-debug recipe | You're hitting weird Slurm/CUDA/vLLM behavior on Insomnia and need verified working settings |
| governance/model_registry.yaml | Canonical registry for the current local-vLLM and WatsonX model contracts, including served model names, repo-facing model IDs, runtime pins, and the standardized MODEL_REVISION for the local Llama mirror |
You need the quick source of truth for which model names/IDs/runtime pins the repo is actually supposed to use |
| slurm_cheatsheet.md | Command-first Slurm reference for submit, watch, estimate start, inspect failures, and historical timing on Insomnia | You need the exact command for sbatch, srun, squeue, sacct, scontrol, or scancel without rereading the longer runbook |
| orchestration_wiring.md | Current repo-side orchestration status for Plan-Execute, Agent-as-Tool, and Hybrid, including what is genuinely wired now versus only adapter-ready | You need to know what #22 / #62 cover in this repo and what is still upstream or mentor-gated |
| experiment_matrix.md | Sharp statement of the core experiment grid, trial policy, Self-Ask tracking, and which optional follow-on cells are worth adding later | You want one defensible answer to "what exactly are we running?" before the matrix sprawls |
| experiment1_capture_plan.md | Capture plan for Experiment 1 (#25): Cell A/B/C config layout, fairness contract, runner requirements, team dependencies, and proposed run sequence through Apr 22 |
You need to know what blocks the Direct / MCP-baseline / MCP-optimized captures and how the artifacts feed Alex's Notebook 02 |
| lane2_int8_kv_status.md | Lane 2 status for #29 (INT8) and #30 (KV-cache) — vLLM 0.19.0 quantization landscape, INT8 deferral rationale + smoke evidence (8979660), chosen KV-cache knob (prefix caching only — fp8 KV tested in smoke 8979532 and deferred due to a vLLM 0.19.0 FA3 kernel constraint under FP16 weights), and recorded Insomnia smoke results |
You need to know what optimizations Cell C bundles, why INT8 is deferred, or how to read the Lane 2 smoke evidence |
| failure_analysis_scaffold.md | Before/after metric pack for #36: outcome / failure-shape / latency / profiling field list, comparison ledger, export contract, comparison-ready status labels |
You need the canonical contract for what the #36 rerun lane has to produce so notebook and paper exports stay joinable |
| failure_taxonomy_evidence.md | Failure taxonomy classification for #35: Berkeley categories, decision ladder, evidence schema, populated Apr 22 evidence pass, paper-safe wording guide, classification workflow |
You need to label observed failures with concrete artifact backing instead of vibes, and you want one evidence row per (run_name, scenario_id, trial_index) |
| failure_visuals_mitigation.md | Visuals scaffold + figure-ready aggregation contract + mitigation ranking rubric + Apr 22 mitigation ranking + promotion gate into #65 / #66 for #64 |
You need to decide which mitigation goes first into implementation/rerun and what figure each visual should render from |
| mitigation_recovery_adjudication.md | Implementation-ready spec for the retry/replan recovery and explicit fault/risk adjudication mitigation rungs | You need to implement or review the follow-on mitigation ladder without creating a full cell-by-mitigation grid |
| scenario_realism_validation.md | Mentor-facing realism-validation pack for the current Smart Grid scenario families, including representative scenarios, known realism gaps, and the concrete questions to send Dhaval | You need to sanity-check whether the current Smart Grid scenarios read like believable transformer maintenance work |
| ps_b_evaluation_methodology.md | Validation rubric for comparing generated PS B scenarios against the hand-crafted Smart Grid set, including duplication checks, acceptance thresholds, and explicit circularity handling | You need the concrete standard Akshat should apply when validating generated scenarios |
| neurips_abstract_outline.md | Working title list, abstract skeleton, and evidence map for the NeurIPS paper lane | You need a prepared outline for the final abstract rather than drafting from scratch under deadline pressure |
| neurips_draft.md | Live NeurIPS paper-writing scaffold for #5 / #39: title, one-paragraph claim, draft abstract, working contribution list, claim ledger, section scaffold, draft prose ready to lift into Overleaf |
You want the paper effort to move beyond outline-only planning into a real draft surface with reusable section text |
| neurips_submission_packet.md | Deadline-facing NeurIPS control packet for #5 / #39 / #47 / #48: submission surface, exact abstract candidate, claim tiers, current result snapshot, figure queue, and blockers |
You need the shortest source of truth for what can be submitted now and what still blocks the full paper |
| neurips_overleaf_transfer_plan.md | Repo-to-Overleaf sync plan for the NeurIPS 2026 project: what was copied, what remains caveated, and which metric sources back paper tables and figures | You need to keep Overleaf aligned with repo evidence without re-deriving the copy order |
| final_report_backport_scaffold.md | Class final report back-port scaffold for #40: IEEE section map, drift-control rules, figure/table requirements, and conversion checklist from the NeurIPS draft |
You need to turn the NeurIPS draft into the class final report without inventing a second source of truth |
| final_presentation_deck.md | Slide-by-slide final presentation draft for #44: deck spine, claims, proof objects, result tables, and backup Q&A prompts |
You need to convert the current paper/report story into the class presentation deck |
| auto_scenario_generation_runbook.md | Runbook for scripts/generate_scenarios.py (#2 prototype): how the generator consumes the support data, output layout under data/scenarios/generated/<batch_id>/, dry-run vs live invocation, promotion path from generated to canonical, scope deferred to #68 scale-up |
You want to produce a candidate Smart Grid scenario batch or read what a generated scenario file actually contains |
| knowledge-base/reference/2026-04-06_watsonx_access.md | WatsonX API setup walkthrough, available models, usage patterns, latency benchmark results (Maverick vs 70B) | You need to onboard your local .venv to hit the hosted Llama models |
| eval_harness_readme.md | End-to-end Windows runbook for AssetOpsBench harness, WatsonX setup, Docker path, scenario-server grading flow, both CODS benchmark tracks (cods_track1, cods_track2), smoke script (../scripts/run_harness_smoke.cmd), and proof expectations for canonical runs | You need to quickly prove harness execution is working this week and run new scenario prompts |
| data_pipeline.tex | Paper-ready LaTeX section describing dataset schemas, shared-key strategy, output formats, reproducibility | You're writing the paper/report and need the data-pipeline section |
| dataset_visualization.png | Historical 6-panel sample visualization of the processed datasets (static smoke test only; ../notebooks/01_data_exploration.ipynb is the reproducible successor) | You want to compare the old static smoke-test image with the new notebook-backed exploration path |
| hpml_datasets.pdf | Tanisha's reference writeup on the 5 Kaggle source datasets (formats, row counts, licensing) | You need background on where the data came from |
| images/ | Inline figures referenced by the .md files | - |
| archive/ | Historical docs that were once live but are now frozen reference artifacts | You need provenance, not the current operating picture |
- knowledge/ - PS B generation support: scenario family matrix, operational context profiles, DGA trend templates, event/alarm templates, WO playbook, and scenario authoring contract with ground-truth field spec.
- knowledge-base/ - Curated project knowledge extracted from references, closeouts, and durable learnings. Current lower-churn references live in knowledge-base/reference/; project learnings live in knowledge-base/learnings/.
- retrospectives/ - Durable closeout records for completed historical work units and long-session backfills.
- ../scripts/README.md - Executable entrypoints and helper scripts.
- ../configs/README.md - Benchmark config schema and cell naming.
- ../data/README.md - Data pipeline and processed dataset policy.
- ../data/scenarios/README.md - Scenario authoring guide and validator entrypoint.
- ../mcp_servers/README.md - Smart Grid MCP server layout and tool surfaces.
- ../benchmarks/README.md - Raw benchmark artifact layout.
- ../notebooks/README.md - Analysis notebook contract.
- ../results/README.md - Derived metrics / figures contract.
- ../profiling/README.md - Profiling capture workflow and wrappers.
- ../planning/ - Index for historical meeting agendas, working notes, and planning snapshots under ../planning/archive/. Current task state now lives in the GitHub Project; historical tracker/spec snapshots live in ../planning/archive/task_tracker.md and ../planning/archive/task_specs.md.
- ../reports/ - Frozen deliverables (mid-point submission PDF, proposal PDFs, draft archive).
- governance/ - Small repo-truth governance artifacts, starting with the model/runtime registry for local vLLM and WatsonX naming/pinning.
- One purpose per file - if a doc is doing two things, split it.
- Date-stamped markdown updates - every doc should have a
*Last updated: YYYY-MM-DD*line near the top. Stale dates are a smell. - Cross-reference other docs by relative path - e.g. compute plan, not absolute URLs. Keeps the repo portable.
- Low-churn reference docs live under
knowledge-base/reference/- class requirements, mentor guidance, and setup references that change less often should live there rather than crowding the top-level index. - Paper-ready content (LaTeX) lives here - finished paper sections can be dropped into Overleaf as
.texfiles. Don't mix draft and final in the same file; use git history for versions. - No shipped deliverables here - if it's a frozen PDF/PPTX/Keynote export that was submitted or emailed, it belongs in
../reports/, notdocs/. - No active planning artifacts here - historical planning records live in
../planning/archive/; agent-coordination surfaces are no longer part of this team repo's documentation tree.