NVC SHOP

Problem Statement

The NVC analytics implementation is fragmented across teams and markets. Some teams use satellite.track, others inject window.digitaldata from server-side scripts, and others use custom helper methods. At the same time, PV requirements are delivered in Excel and manually interpreted, which causes inconsistent implementation, repeated clarification, and regressions.

The process today is not reliably versioned, not fail-safe by default, and not scalable for multi-market delivery.

---

Solution Description

NVC Analytics Agent Platform: a two-stage, contract-first automation model.

1. Stage 1: PV Intelligence Training

• Train a dedicated PV parser tool/skill to understand NVC PV Excel structure.
• It learns exactly which sheet, row, and column hold required event metadata.
• Output is normalized structured data from PV, not direct code generation.

2. Stage 2: Contract-First Implementation

• User asks to implement a specific PV row (or range).
• Agent generates the app-owned contract/schema first.
• Agent pauses for one user validation checkpoint.
• User provides corrections if needed.
• Agent regenerates contract until approved.
• After approval, agent generates app-level implementation, tests, and PR-ready output.

3. Continuous Learning Loop

• Any user correction is saved as a rule/example in tool memory/skill data.
• Future parses use that learning to avoid repeating the same mistake.
• Accuracy improves over time across teams.

4. Architecture Boundary

• App layer owns business semantics and payload shaping.
• Shared SDK is runtime-only: validate, route, dispatch, observe.
• Shared SDK has zero dependency on app code or app/domain TypeScript types.

5. Versioning and Fail-Safe

• SemVer on app-owned contracts (MAJOR.MINOR.PATCH).
• Compatibility checks and release gates in CI.
• Canary rollout, kill-switch controls, and auto-rollback on drift/error thresholds.

---

Business Value / Impact

• Faster PV-to-implementation cycle with lower manual effort.
• Better consistency across teams, apps, and markets.
• Lower regression risk through contract-first validation and controlled rollout.
• Reduced rework due to correction memory and progressive agent learning.
• Strong governance with auditable version history and safety gates.

---

Tech Stack

Backend

• Python 3.x
• FastAPI + Uvicorn
• Redis (shared memory/events)
• Vector retrieval store (FAISS or equivalent)
• FordLLM integration for classification/reasoning
• CI validation pipeline

Agent Layer

• Intent parser
• PV row normalizer
• Contract generator
• Code generator
• Test generator
• PR orchestrator
• Correction-memory updater

Runtime

• App-owned analytics contracts
• Thin shared runtime SDK
• Policy-driven dispatch (satellite.track / digitaldata path)

---

Mandatory End-to-End Flow

1. Train and validate PV parser skill on real NVC PV Excel patterns.
2. Parse PV and select implementation row(s).
3. Generate contract/schema first.
4. Request one user validation checkpoint.
5. Apply corrections and regenerate if needed.
6. Persist corrections into skill/memory.
7. Generate app-level code, tests, and PR artifacts.
8. Enforce semver and compatibility gates.
9. Canary release, monitor, rollback automatically if unhealthy.

https://mdview.io/s/9fff3999