shu/vpp-ai-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
8 Commits 1 Branch 0 Tags 33 MiB
TypeScript 79.8%
Python 20.1%
Shell 0.1%
f681e134cc
Go to file
stewart hu f681e134cc M1: domain schemas, contracts pipeline, ledger and snapshot services 
- packages/domain: zod schemas for the 07-scenario object set with a
  schemaRegistry driving schema export, fixture generation, and Python
  module naming; decimal-string/sha256/curve primitives enforce the
  docs/11 §3.3 representation rules at the type layer
- contracts/: 12 JSON Schemas (draft 2020-12), 12 golden fixtures, 3
  invalid fixtures crafted to fail on both sides (float money, bad
  digest, missing concurrency version)
- skills-py: generated pydantic models (committed, never hand-edited),
  regeneration script, mirror pytest using JSON-mode validation —
  dual-side contract tests agree on all 15 fixtures
- packages/services: content-addressed immutable snapshot store
  (memory + fs, rejects floats), LedgerService v1 with optimistic
  concurrency and the P7 constraint cascade (monthly position bounds
  day-ahead bids; no-anchor bids rejected), quality-gate stub
- cascade band shape is an OPEN-QUESTION A5 placeholder (pro-rata
  daily share ±band) — see ledger.ts checkCascade

All green: tsc typecheck, 41 TS tests, 15 Python tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019u5SLNweVio6ozJX7yfxQr

🔮 View transcript: https://logs.lojong.info/s/e8u90k3t33w590r7b5y7yzqh
2026-09-01 21:50:22 -04:00
contracts M1: domain schemas, contracts pipeline, ledger and snapshot services 2026-09-01 21:50:22 -04:00
docs Scaffold repo for implementation handoff 2026-09-01 21:13:00 -04:00
packages M1: domain schemas, contracts pipeline, ledger and snapshot services 2026-09-01 21:50:22 -04:00
proposal-assets init check in 2026-09-01 19:46:59 -04:00
skills-py M1: domain schemas, contracts pipeline, ledger and snapshot services 2026-09-01 21:50:22 -04:00
.gitignore Scaffold repo for implementation handoff 2026-09-01 21:13:00 -04:00
brainstorming.md Integrate peer review findings into architecture docs 2026-09-01 20:44:12 -04:00
CLAUDE.md Scaffold repo for implementation handoff 2026-09-01 21:13:00 -04:00
GLOSSARY.md Scaffold repo for implementation handoff 2026-09-01 21:13:00 -04:00
package-lock.json M1: domain schemas, contracts pipeline, ledger and snapshot services 2026-09-01 21:50:22 -04:00
package.json M1: domain schemas, contracts pipeline, ledger and snapshot services 2026-09-01 21:50:22 -04:00
proposal.md init check in 2026-09-01 19:46:59 -04:00
README.md Scaffold repo for implementation handoff 2026-09-01 21:13:00 -04:00
ROADMAP.md Scaffold repo for implementation handoff 2026-09-01 21:13:00 -04:00
tsconfig.base.json M1: domain schemas, contracts pipeline, ledger and snapshot services 2026-09-01 21:50:22 -04:00

README.md

VPP AI Platform · 虚拟电厂多时空协同智能运营平台

AI-assisted operations platform for a virtual power plant (VPP) in Hubei, China: five LLM agents propose market bids, resource dispatch, and load-control plans; a deterministic safety chain (rule check → simulation → envelope/human approval → execution permit) governs everything before any external effect. The LLM never computes numbers and never touches the second-level control loop.

Status: architecture/design phase. No implementation code yet. The design is complete and internally consistent (docs 00–13); implementation follows ROADMAP.md, starting with M1.

Orientation

You are… Start with
A coding agent about to implement CLAUDE.md, then docs/00, 01, 09, 11
New to the project docs/00-overview.md → docs/07-scenario-walkthrough.md (the end-to-end reference scenario)
Reviewing the business case proposal.md (申报材料, source of requirements)
Looking for a settled decision docs/adr/
Wondering what's still undecided docs/open-questions.md

Document map (docs are in Chinese; implementation-facing files in English)

Doc Content
00-overview System context, two-plane architecture, business objects
01-principles 9 principles + 8 hard invariants (binding for all code)
02-cognitive-plane Five agents, Runtime, memory, Case Desk
03-safety-chain Proposal state machine, envelopes, permits, staleness
04-control-plane Execution engine, edge autonomy, time/space cascades
05-skills-and-data Skill contracts, five-store data layer, policy packs
06-integration External system boundaries and degraded channels
07-scenario-walkthrough Day-ahead spot bidding, D-1 → D → D+1
08-implementation Stack, LLM abstraction, deployment, milestones
09-runtime-implementation Runtime on Mastra: workflows, suspend/resume, lineage
10-federation Cross-province boundary: signed artifacts only
11-contracts Ports, canonical objects, TS↔Python contract pipeline
12-evaluation Four-layer evals, change gates, KPI definitions
13-risks-failure-modes FMEA, top-5 risks, kill-switch hierarchy

Supporting: brainstorming.md is an independent peer review whose findings were integrated (see docs/01 invariants note); GLOSSARY.md maps Chinese domain terms to canonical code names.

Target repository layout (from docs/09 §7)

packages/
├── domain/       # zod schemas — single source of truth for all business objects
├── runtime/      # Mastra instance, workflows, agents, tool registry, triggers
├── services/     # deterministic services: policy engine, envelopes, ledger, authority
├── adapters/     # anti-corruption layers: trading platform, dispatch, metering
├── evals/        # eval harness, datasets, judges (docs/12 §5)
└── skills-py/    # Python skill services (forecasting, MILP optimization, simulation)
contracts/        # generated JSON Schema + golden fixtures (cross-language contract)