Skip to content

Refactor architecture domains and add evidence-backed cost modeling - #3

Merged
reiase merged 5 commits into
mainfrom
agent/cost-model-providers
Aug 9, 2026
Merged

Refactor architecture domains and add evidence-backed cost modeling#3
reiase merged 5 commits into
mainfrom
agent/cost-model-providers

Conversation

@reiase

@reiase reiase commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Motivation

Blueprinting is an evidence-driven hardware architecture exploration system. The previous source layout still mixed workload semantics, logical mapping, formal derivation, hardware descriptions, cost evidence, and external validation under compiler-shaped packages. That made ownership unclear, encouraged target details to leak into portable plans, and made the base package carry a large optional performance-data bundle.

This PR converges the implementation around the product architecture: formal modeling and verified synthesis are implementation techniques, while workload, mapping, system, evidence, application, and validation remain explicit domains.

What changed

Establish explicit domain boundaries

  • Rename the formal derivation package from blueprinting.compiler to blueprinting.synthesizer.
  • Promote evidence and cost analysis to top-level blueprinting.analysis.
  • Introduce:
    • blueprinting.schema for dependency-free canonical serialization and immutable values;
    • blueprinting.workload for model and scenario facts;
    • blueprinting.mapping for TP/PP/DP strategies and explicit deployment mappings;
    • blueprinting.system for compute, memory, interconnect, and system profiles;
    • blueprinting.validation for Calculon/Vidur adapters and regression gates.
  • Add AST-based dependency-boundary tests to keep the supported architecture acyclic.

Clarify exact-work derivation and late binding

  • Move Transformer training and inference work algebra into sibling synthesizer dialects.
  • Separate training workload facts from logical mapping choices.
  • Keep physical network-tier selection in NetworkTierBinding, supplied only during target/system evaluation.
  • Remove duplicate invocation objects from PortablePlanIR; cost views reconstruct semantic metadata from canonical WorkloadFacts.
  • Reject conflicting canonical and legacy configuration aliases before derivation.
  • Bump changed Transformer pass contracts and planner revisions to v2.

Add the performance evidence plane

  • Add a typed cost query/result protocol, resolver, database, provenance records, and explicit fallback policy.
  • Add analytical roofline, simulator/tabular import, AIConfigurator import, and Vidur profile support.
  • Keep estimates as derived views instead of writing latency into workload or portable-plan facts.
  • Move the optional AIConfigurator snapshot to data/evidence/ and exclude it from base distribution artifacts.

Strengthen application, validation, and packaging contracts

  • Add presentation-neutral shared application reports for training and inference.
  • Replace the legacy root CLI with a small argparse entry point and lazy NiceGUI launch.
  • Keep Calculon and Vidur downstream as comparison oracles; consolidate historical SeqSel reproductions under validation/legacy/.
  • Add strict training and inference baseline gates, late-binding invariants, canonical/legacy boundary tests, CLI tests, and wheel-content checks.
  • Package model/system presets for installed workbench use while excluding optional evidence.
  • Update the bilingual MkDocs design narrative, ADRs, status pages, pass documentation, and architecture SVGs.

Architectural invariants guarded by this PR

  • Workload contracts do not depend on mapping or hardware.
  • Target/deployment details do not enter ModelIR, DistributedTaskIR, or PortablePlanIR.
  • Changing a bound network tier can change a cost projection but cannot change the portable-plan digest.
  • Exact operations, bytes, shapes, and collective payloads have one canonical source of truth.
  • External baselines cannot influence lowering or cost-model construction.
  • Legacy wire tags remain readable even though the Python package layout changes.

Compatibility and migration notes

  • The blueprinting.compiler Python import path is intentionally removed.
  • Historical compiler.* codec tags remain as stable wire identities.
  • Retained Calculon-style configuration keys are accepted only at import boundaries; canonical and legacy spellings must agree when both are supplied.
  • The package root now exposes version metadata instead of re-exporting the legacy simulation stack.
  • AIConfigurator evidence must be loaded explicitly from data/evidence/; it is no longer included in the default wheel or sdist.

Validation

  • uv run pytest: 131 passed, no warnings.
  • Ruff lint and format checks pass across the supported architecture.
  • Calculon/SeqSel training and Vidur inference baseline gates pass.
  • Documentation i18n check validates 31 bilingual page pairs.
  • mkdocs build --strict and SVG XML validation pass.
  • Wheel contract passes: 191 files, 1,182,984 bytes uncompressed, required presets present, optional evidence absent.

Suggested review order

  1. docs/design/modules.{en,zh}.md and the new ADRs for intent.
  2. src/blueprinting/{workload,mapping,system}/ for domain ownership.
  3. src/blueprinting/synthesizer/dialects/transformer/ and lowerings for canonical work derivation.
  4. src/blueprinting/analysis/cost/ for evidence resolution.
  5. src/blueprinting/validation/, boundary tests, and CI/package checks.

Out of scope

This PR does not claim that target plugins, portable-to-concrete planning, resource scheduling, event-level simulation, profiler ingestion, MachineIR emission, or Pareto search are implemented. It establishes and guards the boundaries those capabilities will extend.

@reiase reiase changed the title Enhance cost management with evidence-backed providers and refactor architecture Refactor architecture domains and add evidence-backed cost modeling Aug 9, 2026
@reiase
reiase marked this pull request as draft August 9, 2026 11:02
@reiase
reiase marked this pull request as ready for review August 9, 2026 11:03
@reiase
reiase merged commit 4134fd1 into main Aug 9, 2026
5 checks passed
@reiase
reiase deleted the agent/cost-model-providers branch August 9, 2026 11:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant