diff --git a/.githooks/pre-push b/.githooks/pre-push index 0c89ff143..47dfb917f 100644 --- a/.githooks/pre-push +++ b/.githooks/pre-push @@ -4,4 +4,4 @@ set -euo pipefail repo_root="$(git rev-parse --show-toplevel)" cd "$repo_root" -python scripts/ops/pre_push_gate.py +python scripts/python/ops/pre_push_gate.py diff --git a/.github/prompts/documentation-full-review.prompt.md b/.github/prompts/documentation-full-review.prompt.md new file mode 100644 index 000000000..25ab35cd2 --- /dev/null +++ b/.github/prompts/documentation-full-review.prompt.md @@ -0,0 +1,316 @@ +# Full Documentation Review & Update + +## Objective + +Perform a **comprehensive, critical, document-by-document review** of ALL documentation in the repository — the `docs/` folder and every `README.md` file across the codebase — and update each to reflect the **current state** of the solution with deep technical insights, visual clarity, and cohesive narrative. + +The final documentation set must explain **what Holiday Peak Hub is**, **why it exists**, **how it works**, and **how to operate it** — both visually (Mermaid diagrams, tables, flow charts) and in writing. + +--- + +## Execution Strategy + +Work through the documentation corpus in **7 sequential waves**, each delegated to the appropriate specialist agent. After each wave, the orchestrator validates alignment before proceeding. + +--- + +## Wave 1: Business Context & Value Proposition + +**Agent**: `BusinessStrategist` via `#runSubagent` + +**Scope**: Review and update business-facing documentation. + +**Files to review/update**: +- `docs/architecture/business-summary.md` +- `docs/business_scenarios/README.md` +- `docs/business_scenarios/01-order-to-fulfillment/README.md` +- `docs/business_scenarios/02-product-discovery-enrichment/README.md` +- `docs/business_scenarios/03-returns-refund-processing/README.md` +- `docs/business_scenarios/04-inventory-optimization/README.md` +- `docs/business_scenarios/05-shipment-delivery-tracking/README.md` +- `docs/business_scenarios/06-customer-360-personalization/README.md` +- `docs/business_scenarios/07-product-lifecycle-management/README.md` +- `docs/business_scenarios/08-customer-support-resolution/README.md` +- `docs/business_scenarios/competitive-intelligence-enrichment-search.md` +- `docs/business_scenarios/cost-benefit-enrichment-search.md` +- `docs/business_scenarios/risk-assessment-enrichment-search.md` + +**Acceptance criteria**: +- [ ] Each business scenario document articulates: the business problem, KPIs impacted, how the agentic approach differs from traditional microservices, and measurable value delivered +- [ ] Stakeholder map updated (who benefits: CTO, VP Commerce, Ops Manager, Developer) +- [ ] Domain boundaries documented as bounded contexts with clear ownership +- [ ] Non-functional requirements (SLAs, compliance, scaling targets) stated for each domain +- [ ] Competitive positioning narrative: why agentic retail vs. traditional approaches +- [ ] All documents dated and versioned consistently + +--- + +## Wave 2: Architecture & ADR Review + +**Agent**: `SystemArchitect` via `#runSubagent` + +**Scope**: Review and update all architecture documentation and ADRs for accuracy and completeness. + +**Files to review/update**: +- `docs/architecture/README.md` +- `docs/architecture/architecture.md` +- `docs/architecture/solution-architecture-overview.md` +- `docs/architecture/solution-architecture-diagrams.md` +- `docs/architecture/components.md` +- `docs/architecture/index.md` +- `docs/architecture/design-enrichment-search-flows.md` +- `docs/architecture/eventhub-topology-matrix.md` +- `docs/architecture/maf-integration-rationale.md` +- `docs/architecture/foundry-agents-vs-direct-api-report.md` +- `docs/architecture/crud-service-implementation.md` +- `docs/architecture/architecture-compliance-review.md` +- `docs/architecture/standalone-deployment-guide.md` +- `docs/architecture/test-coverage-gap-analysis.md` +- `docs/architecture/ADRs.md` (index) +- All 27 ADRs in `docs/architecture/adrs/adr-001-*.md` through `adr-027-*.md` + +**Acceptance criteria**: +- [ ] Each ADR follows the standard template: Status, Context, Decision, Consequences, Alternatives Considered +- [ ] ADRs cross-reference related ADRs and link to implementation evidence +- [ ] Architecture overview matches current deployed state (26 agents, CRUD service, UI, Event Hubs, memory tiers, Flux GitOps, AGC edge, APIM) +- [ ] Component responsibility matrix is current and complete +- [ ] Data flow diagrams match actual adapter/event/MCP communication paths +- [ ] Technology stack rationale is documented for every major choice +- [ ] Sequence diagrams validated against actual code paths +- [ ] Pattern catalog (Builder, Adapter, Saga choreography, Tiered Cache) correctly described + +--- + +## Wave 3: Visual Architecture & Diagrams + +**Agent**: `UIDesigner` via `#runSubagent` + +**Scope**: Review and update all visual architecture artifacts for accuracy, consistency, and readability. + +**Files to review/update**: +- `docs/architecture/diagrams/README.md` +- `docs/architecture/diagrams/c4-system-context.drawio` +- `docs/architecture/diagrams/c4-container-azure-runtime.drawio` +- `docs/architecture/diagrams/c4-component-detailed.drawio` +- `docs/architecture/diagrams/c4-component-summary.drawio` +- `docs/architecture/diagrams/holiday-peak-hub-architecture.drawio` +- `docs/architecture/diagrams/sequence-catalog-search.md` +- `docs/architecture/diagrams/sequence-flux-gitops-deployment.md` +- `docs/architecture/diagrams/sequence-foundry-agent-invocation.md` +- `docs/architecture/diagrams/sequence-inventory-health.md` +- `docs/architecture/diagrams/sequence-memory-parallel-io.md` +- `docs/architecture/diagrams/sequence-returns-support.md` +- All inline Mermaid diagrams in `docs/architecture/architecture.md` and `docs/architecture/solution-architecture-overview.md` + +**Acceptance criteria**: +- [ ] All Mermaid diagrams use the repository-standard theme (dark base with `primaryColor:#FFB3BA`, `lineColor:#BAE1FF`) +- [ ] C4 diagrams (draw.io) reflect current system: 26 agents in AKS, CRUD service, UI on SWA, APIM gateway, AGC edge, Event Hubs, three-tier memory, AI Search, Flux GitOps +- [ ] Sequence diagrams match actual flow: FoundryAgentInvoker, memory parallel I/O, MCP tool exposition +- [ ] Visual hierarchy: Context → Container → Component → Code levels clearly separated +- [ ] Consistent icon set across all diagrams (Azure icons for services, custom robot icons for agents) +- [ ] Color palette documented in `docs/architecture/diagrams/README.md` as a style guide +- [ ] Every diagram has a prose caption explaining what it shows and when to use it + +--- + +## Wave 4: Technical Reference — Backend (Python) + +**Agent**: `PythonDeveloper` via `#runSubagent` + +**Scope**: Review and update all Python-related documentation and READMEs. + +**Files to review/update**: +- `lib/README.md` +- `lib/src/README.md` +- `docs/agentic-microservices-reference.md` +- `docs/implementation/README.md` +- `docs/implementation/truth-layer-agents-guide.md` +- `docs/implementation/truth-layer-api.md` +- `docs/implementation/crud-runtime-resilience.md` +- `docs/implementation/telemetry-envelope-v1.md` +- `docs/implementation/per-agent-azd-deployment.md` +- `docs/implementation/single-rg-deployment-runbook.md` +- `docs/implementation/entra-id-setup.md` +- `docs/implementation/architecture-implementation-plan.md` +- `docs/implementation/c4-component-diagram.md` +- `docs/implementation/compliance-analysis.md` +- `docs/implementation/tested-image-promotion.md` +- All 26 agent app READMEs: + - `apps/crm-campaign-intelligence/README.md` + - `apps/crm-profile-aggregation/README.md` + - `apps/crm-segmentation-personalization/README.md` + - `apps/crm-support-assistance/README.md` + - `apps/ecommerce-cart-intelligence/README.md` + - `apps/ecommerce-catalog-search/README.md` + - `apps/ecommerce-checkout-support/README.md` + - `apps/ecommerce-order-status/README.md` + - `apps/ecommerce-product-detail-enrichment/README.md` + - `apps/inventory-alerts-triggers/README.md` + - `apps/inventory-health-check/README.md` + - `apps/inventory-jit-replenishment/README.md` + - `apps/inventory-reservation-validation/README.md` + - `apps/logistics-carrier-selection/README.md` + - `apps/logistics-eta-computation/README.md` + - `apps/logistics-returns-support/README.md` + - `apps/logistics-route-issue-detection/README.md` + - `apps/product-management-acp-transformation/README.md` + - `apps/product-management-assortment-optimization/README.md` + - `apps/product-management-consistency-validation/README.md` + - `apps/product-management-normalization-classification/README.md` + - `apps/search-enrichment-agent/README.md` + - `apps/truth-enrichment/README.md` + - `apps/truth-export/README.md` + - `apps/truth-hitl/README.md` + - `apps/truth-ingestion/README.md` +- `apps/crud-service/README.md` +- `apps/crud-service/src/README.md` +- `apps/README.md` + +**Acceptance criteria**: +- [ ] Each agent README follows a consistent template: Purpose, Domain, Endpoints (REST + MCP), Event Subscriptions, Memory Usage, Model Routing (SLM/LLM), Environment Variables, Local Run, Test Coverage +- [ ] `lib/README.md` documents the framework API surface: BaseRetailAgent, AgentBuilder, FoundryAgentInvoker, MemorySettings, adapters, schemas +- [ ] Async patterns documented: `asyncio.gather` for parallel I/O, `FoundryAgentInvoker` tool forwarding, circuit breaker usage +- [ ] Data model contracts (Pydantic schemas) documented with examples +- [ ] CRUD service README documents all REST endpoints, Event Hub publications, and agent-call patterns +- [ ] Integration patterns documented: how agents call CRUD, how CRUD calls agents, Event Hub choreography + +--- + +## Wave 5: Technical Reference — Frontend (TypeScript) + +**Agent**: `TypeScriptDeveloper` via `#runSubagent` + +**Scope**: Review and update frontend documentation. + +**Files to review/update**: +- `apps/ui/README.md` +- `docs/implementation/ui-crud-route-alignment.md` +- `docs/implementation/ui-ux-modernization-review.md` + +**Acceptance criteria**: +- [ ] UI README documents: Next.js 15 App Router structure, component catalog, state management (React Query), Tailwind design tokens, deployment to SWA +- [ ] Route structure fully documented with page-level component responsibilities +- [ ] Agent robot overlay system and executive demo flow documented +- [ ] API client architecture (matching ADR-016) described with examples +- [ ] Accessibility compliance (WCAG 2.2 AA) documented + +--- + +## Wave 6: Operations & Governance + +**Agent**: `PlatformEngineer` via `#runSubagent` + +**Scope**: Review and update all operational and governance documentation. + +**Files to review/update**: +- `docs/ops/catalog-search-readiness-503-runbook.md` +- `docs/ops/agc-bisection-2026-04-21.md` +- `docs/governance/README.md` +- `docs/governance/backend-governance.md` +- `docs/governance/frontend-governance.md` +- `docs/governance/infrastructure-governance.md` +- `docs/governance/dependency-audit-wave0.md` +- `docs/governance/repository-hygiene-cleanup.md` +- `docs/governance/security-exception-register.md` +- `docs/governance/security-triage-weekly.md` +- `docs/governance/self-healing-rbac-matrix.md` +- `docs/governance/self-healing-rollout-runbook.md` +- `docs/IMPLEMENTATION_ROADMAP.md` +- `docs/roadmap/README.md` +- All roadmap items `docs/roadmap/001-*.md` through `docs/roadmap/014-*.md` +- `docs/demos/README.md` +- `docs/demos/live-demo-search-enrichment-hitl.md` +- `.infra/README.md` +- `.infra/modules/static-web-app/README.md` +- `.infra/modules/shared-infrastructure/README.md` +- `CONTRIBUTING.md` +- `SECURITY.MD` + +**Acceptance criteria**: +- [ ] Deployment procedures current: azd-based provisioning, Flux GitOps for AKS, AGC edge routing, tested image promotion +- [ ] Runbooks tested: catalog-search 503, AGC bisection, self-healing rollout all verified against current infra +- [ ] Monitoring and alerting documented: Application Insights, telemetry envelope v1, health probes +- [ ] Incident response playbook updated with self-healing epic outcomes +- [ ] Security governance current: Entra ID auth, RBAC matrix, Key Vault, secret rotation +- [ ] CI/CD pipeline documentation matches actual workflows (`.github/workflows/`) +- [ ] Environment setup prerequisites verified (Python 3.13, Node 20, uv, azd, Docker) +- [ ] Roadmap items marked as completed/in-progress/planned match actual codebase state + +--- + +## Wave 7: Root-Level README & Documentation Hub + +**Agent**: `TechLeadOrchestrator` (self) — final synthesis pass + +**Scope**: Update the root README and documentation hub after all specialist waves complete. + +**Files to review/update**: +- `README.MD` (root) +- `docs/README.md` (documentation hub) +- `docs/project-status.md` +- `docs/backend_plan.md` +- `docs/crud-features-map.md` +- `mkdocs/README.md` +- `CHANGELOG.md` (verify consistency, do not rewrite) + +**Acceptance criteria**: +- [ ] Root README is the definitive 60-second pitch: what, why, how, quick start, architecture diagram, links +- [ ] Documentation hub (`docs/README.md`) serves as index with clear navigation for each audience (developer, architect, operator, business stakeholder) +- [ ] Project status reflects actual state: test count, coverage, deployed services, open issues +- [ ] All cross-references between documents are valid (no broken links) +- [ ] Version/date stamps are consistent across all updated documents +- [ ] `backend_plan.md` and `crud-features-map.md` reflect current implementation (not aspirational) + +--- + +## Cross-Cutting Quality Gates (Apply to ALL Waves) + +Every updated document MUST satisfy: + +1. **Accuracy** — Content matches current codebase (verify by reading source files before writing) +2. **Visual richness** — Every conceptual section includes at least one visual: Mermaid diagram, table, or flow chart +3. **Consistent formatting** — Markdown heading hierarchy, code block languages specified, tables aligned +4. **Date & version** — Header with `Last Updated: YYYY-MM-DD` and relevant version/PR reference +5. **Audience awareness** — Documents state who they are for (developer, architect, operator, business) +6. **No stale content** — Remove references to features not yet implemented; mark aspirational items clearly as "Planned" +7. **Mermaid theme** — All Mermaid diagrams use the repository-standard theme block: + ``` + %%{init: {'theme':'base', 'themeVariables': { + 'primaryColor':'#FFB3BA', + 'primaryTextColor':'#000', + 'primaryBorderColor':'#FF8B94', + 'lineColor':'#BAE1FF', + 'secondaryColor':'#BAE1FF', + 'tertiaryColor':'#FFFFFF' + }}}%% + ``` +8. **Linking** — Documents cross-reference related docs using relative paths +9. **Conciseness** — No filler paragraphs; every sentence adds information + +--- + +## Source-of-Truth References + +Before updating any document, agents MUST read relevant source files to ensure accuracy: + +| Domain | Source files to read | +|--------|---------------------| +| Agent framework | `lib/src/holiday_peak_lib/agents/`, `lib/src/holiday_peak_lib/agents/memory/` | +| CRUD service | `apps/crud-service/src/` | +| Individual agents | `apps//src/main.py`, `apps//src/adapters.py` | +| UI | `apps/ui/app/`, `apps/ui/components/` | +| Infrastructure | `.infra/`, `.github/workflows/`, `k8s/` | +| Configuration | `pyproject.toml`, `azure.yaml`, environment variables | +| Tests | `lib/tests/`, `apps/**/tests/`, `conftest.py` | +| ADRs | `docs/architecture/adrs/` | + +--- + +## Execution Notes + +- Process documents **sequentially within each wave** (one file at a time, deep review) +- For each file: **read current content → read relevant source code → identify gaps/inaccuracies → rewrite with full detail** +- Do NOT create new files unless a critical gap is identified (prefer updating existing) +- Do NOT delete existing content without replacement — preserve institutional knowledge +- Mark any document that cannot be fully updated (e.g., missing source code) with a `` comment +- Commit message convention: `docs: update [filename] — [brief reason]` diff --git a/.github/skills/agent-e2e-validation/SKILL.md b/.github/skills/agent-e2e-validation/SKILL.md index 4df41ad51..a7fcaa959 100644 --- a/.github/skills/agent-e2e-validation/SKILL.md +++ b/.github/skills/agent-e2e-validation/SKILL.md @@ -33,7 +33,7 @@ The dev environment is subject to MCAPSGov nightly automation that stops Postgre ### Step 0: Run the Start-Dev-Environment Script ```powershell -./scripts/start-dev-environment.ps1 +./scripts/powershell/ops/start-dev-environment.ps1 ``` **What it does (in order)**: @@ -700,13 +700,211 @@ After individual agent validation, run these cross-domain scenarios that exercis | 4 | **Return Processing Flow** | CRUD returns → support-assistance → returns-support → inventory update | `POST /api/returns` | Return processed, logistics arranged, stock updated | | 5 | **Campaign Attribution Loop** | CRUD order → campaign-intelligence → profile-aggregation → segmentation-personalization | `POST /api/orders` | Campaign attribution updated, profile refreshed, segment recalculated | +## SSE Streaming Validation + +SSE (Server-Sent Events) streaming validates that agents can deliver progressive token output for long-form responses. This is critical for UX responsiveness — users see incremental results rather than waiting for a full response. + +### SSE Routing Architecture + +``` +Client → APIM /agents/{svc}/invoke/stream → Agent /invoke/stream → SSE text/event-stream +``` + +> **Known limitation**: APIM must have an explicit operation defined for `/agents/{service-name}/invoke/stream` per agent. If the APIM API definition only covers `/invoke`, the `/invoke/stream` route will return 502. + +### SSE Test Matrix + +Test SSE on at least one agent per domain. The following agents are the primary SSE targets: + +| Agent | Test Prompt | Expected Behavior | +|-------|-------------|-------------------| +| ecommerce-catalog-search | `{"query": "Best gear for a week-long Swiss Alps hike", "limit": 8, "mode": "intelligent"}` | Progressive product results + reasoning | +| crm-support-assistance | `{"query": "Review my entire interaction history and suggest improvements"}` | Streaming analytical response | +| inventory-health-check | `{"query": "Generate a full inventory health report with Q1 recommendations"}` | Streaming report sections | +| logistics-eta-computation | `{"query": "Analyze delivery trends over 6 months and predict next month on-time rate"}` | Streaming predictive analysis | +| product-management-normalization-classification | `{"query": "Analyze classification accuracy and recommend taxonomy improvements"}` | Streaming taxonomy analysis | +| truth-hitl | `{"query": "Generate a HITL reviewer productivity report"}` | Streaming metrics report | + +### SSE Validation Script + +```powershell +$APIM_BASE = $env:APIM_BASE +$sseTests = @( + @{svc="ecommerce-catalog-search"; body='{"query":"Best hiking gear for Swiss Alps","limit":8,"mode":"intelligent"}'} + @{svc="crm-support-assistance"; body='{"query":"Review interaction history and suggest improvements"}'} + @{svc="inventory-health-check"; body='{"query":"Full inventory health report with Q1 recommendations"}'} + @{svc="logistics-eta-computation"; body='{"query":"Delivery trends over 6 months, predict next month"}'} + @{svc="product-management-normalization-classification"; body='{"query":"Classification accuracy and taxonomy improvements"}'} + @{svc="truth-hitl"; body='{"query":"HITL reviewer productivity report"}'} +) + +foreach ($test in $sseTests) { + $sw = [System.Diagnostics.Stopwatch]::StartNew() + try { + $req = [System.Net.HttpWebRequest]::Create("$APIM_BASE/agents/$($test.svc)/invoke/stream") + $req.Method = "POST" + $req.ContentType = "application/json" + $req.Timeout = 15000 + $bytes = [System.Text.Encoding]::UTF8.GetBytes($test.body) + $reqStream = $req.GetRequestStream() + $reqStream.Write($bytes, 0, $bytes.Length) + $reqStream.Close() + $resp = $req.GetResponse() + $sw.Stop() + $contentType = $resp.ContentType + $resp.Close() + if ($contentType -like "*event-stream*") { + Write-Host "[OK] $($test.svc) SSE: $($sw.ElapsedMilliseconds)ms" -ForegroundColor Green + } else { + Write-Host "[WARN] $($test.svc) SSE: $($sw.ElapsedMilliseconds)ms - ContentType=$contentType (expected text/event-stream)" -ForegroundColor Yellow + } + } catch { + $sw.Stop() + Write-Host "[FAIL] $($test.svc) SSE: $($sw.ElapsedMilliseconds)ms - $($_.Exception.Message)" -ForegroundColor Red + } +} +``` + +### SSE Acceptance Criteria + +- [ ] `Content-Type: text/event-stream` returned (not `application/json`) +- [ ] First byte received within 3 seconds (first token SLA) +- [ ] Response streams incrementally (not buffered as a single chunk) +- [ ] HTTP 200 status (not 502 Bad Gateway) +- [ ] At least 1 agent per domain successfully streams + +### SSE Failure Investigation + +| Symptom | Likely Cause | Fix | +|---------|-------------|-----| +| 502 Bad Gateway | APIM route for `/invoke/stream` not defined for this agent | Add operation to APIM API definition | +| Timeout (no response) | Agent SSE handler not implemented or Foundry streaming disabled | Check `FOUNDRY_STREAM` env var, verify agent supports streaming | +| Full response in single chunk | APIM or reverse proxy buffering | Check APIM policy for `forward-request` buffer settings | +| 200 but `application/json` | Agent returning sync response on stream endpoint | Check agent code — `invoke/stream` route may be falling back to sync | + +--- + +## MCP Tool Validation + +MCP (Model Context Protocol) tools enable structured agent-to-agent communication. Each agent can expose typed tool endpoints that return structured data (dicts) for downstream consumption by other agents. + +### MCP Routing Architecture + +``` +Calling Agent → APIM /agents/{svc}/mcp/{tool_name} → Target Agent POST /mcp/{tool_name} → Structured dict response +``` + +### MCP Prerequisites + +1. **Agent must register integrations** — check via `GET /agents/{svc}/integrations` + - If `integrations_registered: 0`, MCP tools are not deployed for that agent +2. **APIM must route `/mcp/*`** — wildcard routing to the agent's MCP endpoints +3. **Tool names must be known** — each agent documents its available MCP tools in its README + +### MCP Test Matrix + +One MCP tool call per domain: + +| Agent | Tool | Payload | Expected Response | +|-------|------|---------|------------------| +| ecommerce-catalog-search | `search_products` | `{"query": "winter boots", "limit": 3}` | Dict with `products` array, each with `id`, `title`, `score` | +| ecommerce-cart-intelligence | `get_cart_recommendations` | `{"user_id": "test-user-1"}` | Dict with `recommendations` array of product IDs | +| crm-profile-aggregation | `get_profile_context` | `{"user_id": "user-1"}` | Dict with `demographics`, `preferences`, `history` | +| crm-support-assistance | `create_support_ticket` | `{"issue": "damaged_product", "order_id": "ORD-001"}` | Dict with `ticket_id`, `priority`, `assignee` | +| inventory-alerts-triggers | `dispatch_alert` | `{"sku": "SKU-001", "alert_type": "low_stock"}` | Dict with `alert_id`, `severity`, `actions` | +| inventory-reservation-validation | `check_reservation` | `{"reservation_id": "RES-001"}` | Dict with `status`, `expiry`, `allocated_quantity` | +| logistics-carrier-selection | `get_carrier_routing` | `{"destination": "São Paulo, Brazil", "weight_kg": 2}` | Dict with `carriers` array, each with `name`, `cost`, `eta` | +| logistics-eta-computation | `calculate_eta` | `{"shipment_id": "SHIP-001"}` | Dict with `eta`, `confidence`, `factors` | +| product-management-acp-transformation | `transform_to_acp` | `{"entity_id": "SKU-001"}` | Dict with ACP-formatted attributes | +| product-management-consistency-validation | `check_consistency` | `{"entity_id": "SKU-001"}` | Dict with `violations`, `severity` | + +### MCP Validation Script + +```powershell +$APIM_BASE = $env:APIM_BASE +$mcpTests = @( + @{svc="ecommerce-catalog-search"; tool="search_products"; body='{"query":"winter boots","limit":3}'} + @{svc="ecommerce-cart-intelligence"; tool="get_cart_recommendations"; body='{"user_id":"test-user-1"}'} + @{svc="crm-profile-aggregation"; tool="get_profile_context"; body='{"user_id":"user-1"}'} + @{svc="crm-support-assistance"; tool="create_support_ticket"; body='{"issue":"damaged_product","order_id":"ORD-001"}'} + @{svc="inventory-alerts-triggers"; tool="dispatch_alert"; body='{"sku":"SKU-001","alert_type":"low_stock"}'} + @{svc="inventory-reservation-validation"; tool="check_reservation"; body='{"reservation_id":"RES-001"}'} + @{svc="logistics-carrier-selection"; tool="get_carrier_routing"; body='{"destination":"Sao Paulo, Brazil","weight_kg":2}'} + @{svc="logistics-eta-computation"; tool="calculate_eta"; body='{"shipment_id":"SHIP-001"}'} + @{svc="product-management-acp-transformation"; tool="transform_to_acp"; body='{"entity_id":"SKU-001"}'} + @{svc="product-management-consistency-validation"; tool="check_consistency"; body='{"entity_id":"SKU-001"}'} +) + +foreach ($test in $mcpTests) { + $url = "$APIM_BASE/agents/$($test.svc)/mcp/$($test.tool)" + $sw = [System.Diagnostics.Stopwatch]::StartNew() + try { + $r = Invoke-RestMethod -Uri $url -Method POST -Body $test.body -ContentType "application/json" -TimeoutSec 10 + $sw.Stop() + Write-Host "[OK] $($test.svc)/$($test.tool): $($sw.ElapsedMilliseconds)ms" -ForegroundColor Green + } catch { + $sw.Stop() + $status = $_.Exception.Response.StatusCode.value__ + Write-Host "[FAIL] $($test.svc)/$($test.tool): $($sw.ElapsedMilliseconds)ms - HTTP $status" -ForegroundColor Red + } +} +``` + +### MCP Acceptance Criteria + +- [ ] At least 2 MCP tool calls succeed per domain (10 total minimum) +- [ ] All successful responses return structured dicts (not plain text) +- [ ] Response time < 5 seconds per call +- [ ] No 500 errors (indicates tool handler crash) +- [ ] Integrations endpoint reports `integrations_registered > 0` for agents with MCP tools + +### MCP Failure Investigation + +| Symptom | Likely Cause | Fix | +|---------|-------------|-----| +| 404 Not Found | MCP tool not registered or APIM route missing | Check `GET /integrations` → if `integrations_registered: 0`, MCP not deployed | +| 500 Internal Server Error | Tool handler crash | Check agent pod logs for stack trace | +| 502 Bad Gateway | APIM cannot reach agent MCP endpoint | Verify APIM backend config and AKS service routing | +| Timeout (> 10s) | Tool performing expensive operation | Check if tool depends on external service (Foundry, Cosmos) that is slow | +| Empty response `{}` | Tool executed but returned no data | Likely no matching data in store; verify test data exists | + +### MCP Readiness Check + +Before running MCP tests, verify which agents have tools registered: + +```powershell +$APIM_BASE = $env:APIM_BASE +$agents = @( + "ecommerce-catalog-search", "ecommerce-cart-intelligence", + "crm-profile-aggregation", "crm-support-assistance", + "inventory-alerts-triggers", "inventory-reservation-validation", + "logistics-carrier-selection", "logistics-eta-computation", + "product-management-acp-transformation", "product-management-consistency-validation" +) + +foreach ($agent in $agents) { + try { + $r = Invoke-RestMethod -Uri "$APIM_BASE/agents/$agent/integrations" -TimeoutSec 5 + $count = if ($r.integrations_registered) { $r.integrations_registered } else { 0 } + $color = if ($count -gt 0) { "Green" } else { "Yellow" } + Write-Host "[$count tools] $agent" -ForegroundColor $color + } catch { + Write-Host "[ERROR] $agent - $($_.Exception.Message)" -ForegroundColor Red + } +} +``` + +> **If all agents report `integrations_registered: 0`**, MCP tools are not deployed in this environment. Document this finding and file a GitHub issue (see Defect Tracking section below). + +--- + ## Execution Workflow ### Phase 1: Infrastructure (mandatory, 5-10 min) ```powershell # Step 1: Recover infrastructure -./scripts/start-dev-environment.ps1 +./scripts/powershell/ops/start-dev-environment.ps1 # Step 2: Resolve APIM base URL $azdVars = azd env get-values | ConvertFrom-StringData @@ -761,11 +959,21 @@ Execute the testing plan tables above, domain by domain: **Total: 260 individual test cases** -### Phase 4: Cross-Domain Integration (15-20 min) +### Phase 4: SSE Streaming Validation (5-10 min) + +Run the SSE Streaming Validation script (see section above). Target: at least 1 agent per domain returns `text/event-stream` with first byte < 3s. + +### Phase 5: MCP Tool Validation (5-10 min) + +1. Run the MCP Readiness Check to confirm which agents have tools registered. +2. Run the MCP Validation Script against all registered agents. +3. Skip agents reporting `integrations_registered: 0` — document as an environment gap. + +### Phase 6: Cross-Domain Integration (15-20 min) Execute the 5 cross-domain integration scenarios listed above. -### Phase 5: Results Summary +### Phase 7: Results Summary For each agent, record: @@ -785,12 +993,16 @@ For each agent, record: - [ ] All "Medium" complexity tests demonstrate context awareness - [ ] All "High" complexity tests demonstrate multi-step reasoning - [ ] At least 3 Event Hub async chains verified end-to-end -- [ ] At least 2 MCP tool calls verified per domain -- [ ] At least 2 SSE streaming responses verified (first token < 3s) +- [ ] At least 2 MCP tool calls verified per domain (or documented as deployment gap) +- [ ] At least 1 SSE streaming response per domain verified (first token < 3s) +- [ ] MCP readiness check run — `integrations_registered` documented per agent +- [ ] SSE `Content-Type: text/event-stream` confirmed on at least 1 agent per domain - [ ] All 5 cross-domain integration scenarios completed - [ ] No `degraded_fallback` responses from catalog-search - [ ] Results summary table completed for all agents - [ ] All failures documented with timestamp, endpoint, status, and response body +- [ ] GitHub issues created for all P1/P2 failures found during validation +- [ ] GitHub issues created for P3/P4 gaps (SSE routing, MCP deployment) if applicable ## Investigation Playbook @@ -834,3 +1046,163 @@ If multiple agents fail, return to the Pre-Flight Infrastructure Recovery sectio 2. PostgreSQL state: `az postgres flexible-server show -g $RG -n $PG --query "state"` 3. Event Hub namespace health: Azure Portal → Event Hubs → Activity log 4. APIM health: Azure Portal → APIM → API health + +--- + +## Defect Tracking: Creating GitHub Issues + +When a validation run discovers a problem, **always** create a tracked GitHub issue. Do not rely on chat logs or notes — the issue is the canonical record of the defect. + +### Mandatory: Deep Investigation Before Filing + +**Do NOT create an issue based solely on an HTTP error code.** Before filing, you MUST complete the Investigation Playbook escalation path: + +1. **Level 1 — Surface Diagnostics**: Confirm the failure is reproducible. Capture pod status, recent logs, and APIM proxy response. +2. **Level 2 — Dependency Diagnosis**: Determine whether the failure originates in the agent, a downstream dependency (Foundry, Redis, Cosmos, Event Hub), or the APIM gateway. +3. **Level 3 — Deep Investigation** (for P1/P2): Gather full pod describe, resource utilization, network connectivity test results, and self-healing status. +4. **Level 4 — Infrastructure Recovery** (if multiple agents fail simultaneously): Attempt recovery before filing. If recovery resolves the issue, no issue is needed — document it in the results summary instead. + +**Minimum evidence required per severity:** + +| Severity | Minimum Investigation Level | Required Evidence in Issue | +|----------|----------------------------|----------------------------| +| **P1** | Level 3 complete | Pod logs, describe output, root cause hypothesis, failed recovery attempt (if applicable) | +| **P2** | Level 2 complete | Pod logs, dependency diagnosis, reproduction steps with exact payloads | +| **P3** | Level 1 complete | HTTP status + response body, pod status confirmation, basic log snippet | +| **P4** | Level 1 complete | HTTP status + response body, expected vs actual behavior | + +> **Rationale**: Issues without investigation evidence get triaged slower and often require the same diagnostic steps the validator already had access to. Front-loading investigation saves the team 15-30 minutes per issue. + +### When to Create an Issue + +| Condition | Action | +|-----------|--------| +| Agent returns 500 on invoke | File as **bug** with `P1` or `P2` severity | +| Agent returns 502 on SSE or MCP | File as **bug** if agent-side; **chore** if APIM routing gap | +| Agent timeout exceeds SLA (> 8s sync, > 5s MCP) | File as **bug** with `performance` label | +| MCP tools not registered (`integrations_registered: 0`) | File as **chore** — deployment gap | +| Event Hub event not consumed within 30s | File as **bug** — consumer connectivity | +| CRUD endpoint not reachable (non-auth failure) | File as **bug** with `P1` severity | +| Degraded fallback in catalog-search | File as **bug** — AI pipeline issue | +| Any agent health check fails | File as **bug** with `P1` severity | + +### Issue Template + +Use this structure when creating issues via `gh issue create`: + +```markdown +## Summary +[One sentence describing the defect] + +## Environment +- **Validation date**: YYYY-MM-DD +- **APIM base**: [URL] +- **AKS cluster state**: Running / Recovered +- **Affected agent(s)**: [list] + +## Reproduction Steps +1. [Exact endpoint called] +2. [Exact payload sent] +3. [Response received] + +## Expected Behavior +[What should have happened per the E2E validation skill NFRs] + +## Actual Behavior +[What actually happened — include HTTP status, response body, and latency] + +## Evidence +- **HTTP status**: [code] +- **Response body** (truncated if large): +```json +[paste response] +``` +- **Agent logs** (if accessible): +``` +[paste relevant log lines] +``` +- **Latency**: [ms] + +## Classification +- **Severity**: P1 / P2 / P3 / P4 +- **Category**: agent-invoke / sse-streaming / mcp-tool / event-hub / infrastructure / apim-routing +- **Agent class**: sync / async (per ADR-024 Part 4) + +## Suggested Fix +[Optional — if root cause is obvious from logs, suggest the fix direction] +``` + +### Issue Creation Command + +```powershell +# Single-agent failure (e.g., crm-campaign-intelligence 500) +gh issue create ` + --title "bug: crm-campaign-intelligence returns 500 on invoke (NonRecordingSpan)" ` + --label "bug,P1,agent-invoke,crm" ` + --body @issue-body.md + +# APIM routing gap (e.g., SSE 502 for non-catalog agents) +gh issue create ` + --title "chore: APIM missing /invoke/stream route for non-catalog agents" ` + --label "chore,P3,apim-routing,sse-streaming" ` + --body @issue-body.md + +# MCP deployment gap +gh issue create ` + --title "chore: MCP tools not registered (integrations_registered=0) across all agents" ` + --label "chore,P3,mcp-tool,deployment" ` + --body @issue-body.md +``` + +### Severity Guidelines + +| Severity | Criteria | Response Time | +|----------|----------|---------------| +| **P1** | Agent completely non-functional (500, crash loop) | Fix within 24h | +| **P2** | Agent partially degraded (intermittent failures, SLA breach > 2x) | Fix within 3 days | +| **P3** | Feature gap (SSE/MCP not routed, non-critical path) | Fix within sprint | +| **P4** | Minor (cosmetic, documentation mismatch, cold-start delay) | Backlog | + +### Label Taxonomy + +| Label | Meaning | +|-------|---------| +| `bug` | Defect in existing functionality | +| `chore` | Infrastructure/deployment/config gap | +| `P1` through `P4` | Priority/severity | +| `agent-invoke` | `/invoke` endpoint failure | +| `sse-streaming` | `/invoke/stream` endpoint failure | +| `mcp-tool` | `/mcp/{tool}` endpoint failure | +| `event-hub` | Async event processing failure | +| `apim-routing` | APIM gateway misconfiguration | +| `infrastructure` | AKS, PostgreSQL, Redis, Cosmos infrastructure | +| `performance` | SLA breach without functional failure | +| Domain labels: `crm`, `ecommerce`, `inventory`, `logistics`, `product-management`, `truth-layer` | Domain scope | + +### Post-Issue Workflow + +1. **Create issue** with the template above +2. **Assign** to the appropriate domain team (use issue label to signal) +3. **Link to ADR** if applicable (e.g., ADR-024 Part 4 for mode-related issues) +4. **Branch naming**: `bug/{issue-id}-short-description` or `chore/{issue-id}-short-description` +5. **PR must reference** the issue number (e.g., `Closes #NNN`) +6. **Re-validate** after fix is deployed — re-run the specific failing test from this skill +7. **Close issue** only after re-validation passes + +### Batch Issue Creation After Full Validation + +After completing a full validation run, create issues for ALL failures found: + +```powershell +# Example: Batch create from validation results +$failures = @( + @{title="bug: crm-campaign-intelligence 500 on invoke"; labels="bug,P1,agent-invoke,crm"; body="NonRecordingSpan.attributes error..."} + @{title="chore: APIM /invoke/stream returns 502 for 24/26 agents"; labels="chore,P3,apim-routing,sse-streaming"; body="Only catalog-search has SSE route..."} + @{title="chore: MCP integrations_registered=0 across all agents"; labels="chore,P3,mcp-tool,deployment"; body="No agent reports registered MCP tools..."} +) + +foreach ($f in $failures) { + gh issue create --title $f.title --label $f.labels --body $f.body + Start-Sleep -Seconds 2 # Rate limit courtesy +} +``` diff --git a/.github/workflows/deploy-azd.yml b/.github/workflows/deploy-azd.yml index 5bafe47b6..eb1825627 100644 --- a/.github/workflows/deploy-azd.yml +++ b/.github/workflows/deploy-azd.yml @@ -1609,7 +1609,7 @@ jobs: set -euo pipefail echo "Verifying prompt sha256 match between repo and image for ${SERVICE_NAME}..." docker pull "$IMAGE_REF" >/dev/null - python3 scripts/ci/verify_image_prompt.py \ + python3 scripts/python/ci/verify_image_prompt.py \ --service "$SERVICE_NAME" \ --image-ref "$IMAGE_REF" @@ -1986,9 +1986,9 @@ jobs: sudo apt-get install -y -qq postgresql-client >/dev/null fi - chmod +x ./scripts/ops/reconcile-postgres-password.sh + chmod +x ./scripts/shell/ops/reconcile-postgres-password.sh set +e - ./scripts/ops/reconcile-postgres-password.sh \ + ./scripts/shell/ops/reconcile-postgres-password.sh \ --subscription-id "${AZURE_SUBSCRIPTION_ID}" \ --resource-group "${RESOURCE_GROUP_NAME}" \ --server-name "${SERVER_NAME}" \ @@ -2006,7 +2006,7 @@ jobs: 2) echo "::error::Postgres admin password probe FAILED with invalid_password." >&2 echo "::error::Key Vault secret 'postgres-admin-password' is out of sync with the Flexible Server admin password." >&2 - echo "::error::Run: scripts/ops/reconcile-postgres-password.sh --mode rotate-from-keyvault --resource-group ${RESOURCE_GROUP_NAME} --server-name ${SERVER_NAME} --key-vault-name ${KV_NAME}" >&2 + echo "::error::Run: scripts/shell/ops/reconcile-postgres-password.sh --mode rotate-from-keyvault --resource-group ${RESOURCE_GROUP_NAME} --server-name ${SERVER_NAME} --key-vault-name ${KV_NAME}" >&2 exit 1 ;; 3) @@ -3012,7 +3012,7 @@ jobs: if [ -n "$project_name" ]; then args+=(--project-name "$project_name") fi - if ! python3 scripts/ci/verify_foundry_prompt.py "${args[@]}"; then + if ! python3 scripts/python/ci/verify_foundry_prompt.py "${args[@]}"; then FAIL=1 fi done @@ -4239,8 +4239,8 @@ jobs: shell: bash run: | set -euo pipefail - chmod +x scripts/ops/watchdog-apim-agc-swa-drift.sh - scripts/ops/watchdog-apim-agc-swa-drift.sh + chmod +x scripts/shell/ops/watchdog-apim-agc-swa-drift.sh + scripts/shell/ops/watchdog-apim-agc-swa-drift.sh env: PROJECT_NAME: ${{ inputs.projectName }} ENVIRONMENT: ${{ inputs.environment }} diff --git a/.github/workflows/governance-audit.yml b/.github/workflows/governance-audit.yml index 9c96a4f0e..90951112b 100644 --- a/.github/workflows/governance-audit.yml +++ b/.github/workflows/governance-audit.yml @@ -22,7 +22,7 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} GITHUB_REPOSITORY: ${{ github.repository }} run: | - python scripts/ops/audit_main_governance.py \ + python scripts/python/ops/audit_main_governance.py \ --repo "$GITHUB_REPOSITORY" \ --required-check lint \ --required-check test \ diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index b0ef21687..a5db3390d 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -19,8 +19,9 @@ on: - apps/** - docs/architecture/** - docs/governance/** - - scripts/ops/** - - scripts/ci/** + - scripts/python/** + - scripts/shell/** + - scripts/powershell/** - .github/prompts/** - .github/agents/** - .github/skills/** @@ -74,14 +75,14 @@ jobs: python -m mypy --config-file pyproject.toml --ignore-missing-imports --follow-imports=skip lib/src/holiday_peak_lib/agents/service_agent.py lib/src/holiday_peak_lib/agents/memory/builder.py - name: Validate canonical event schema contracts run: | - python scripts/ops/check_event_schema_contracts.py + python scripts/python/ops/check_event_schema_contracts.py - name: Check prompt and agent governance consistency run: | - python scripts/ops/check_prompt_agent_consistency.py --report-file governance-drift-report.md + python scripts/python/ops/check_prompt_agent_consistency.py --report-file governance-drift-report.md - name: Validate governance and architecture docs links run: | set -o pipefail - python scripts/ops/check_markdown_links.py --roots docs/governance docs/architecture | tee architecture-link-drift-report.txt + python scripts/python/ops/check_markdown_links.py --roots docs/governance docs/architecture | tee architecture-link-drift-report.txt - name: Block stale canonical governance references in agent docs run: | if grep -RInE "OPERATIONAL-WORKFLOWS\.md|REPOSITORY-SURFACES\.md|governance-map\.md" .github/agents; then @@ -90,7 +91,7 @@ jobs: fi - name: Validate K8s resource name length (63-char limit) run: | - python scripts/ci/validate_k8s_name_length.py + python scripts/python/ci/validate_k8s_name_length.py - name: Upload governance drift reports if: always() uses: actions/upload-artifact@v4 diff --git a/.github/workflows/ui-contract-gate.yml b/.github/workflows/ui-contract-gate.yml index d08ff52d3..4799869fb 100644 --- a/.github/workflows/ui-contract-gate.yml +++ b/.github/workflows/ui-contract-gate.yml @@ -9,7 +9,7 @@ on: - .github/workflows/deploy-ui-swa.yml - .github/workflows/deploy-azd.yml - .github/workflows/ui-contract-gate.yml - - scripts/ci/validate_swa_hybrid_contract.py + - scripts/python/ci/validate_swa_hybrid_contract.py pull_request: branches: - main @@ -36,7 +36,7 @@ jobs: python-version: '3.12' - name: Validate SWA hybrid runtime contract - run: python scripts/ci/validate_swa_hybrid_contract.py + run: python scripts/python/ci/validate_swa_hybrid_contract.py - name: Setup Node.js uses: actions/setup-node@v4 diff --git a/.infra/README.md b/.infra/README.md index 73a4d6b14..79d75d09d 100644 --- a/.infra/README.md +++ b/.infra/README.md @@ -1,5 +1,7 @@ # Infrastructure Management +**Last Updated**: 2026-04-30 + This folder contains all infrastructure-as-code (Bicep) and deployment tooling for Holiday Peak Hub. All infrastructure uses [Azure Verified Modules (AVM)](https://azure.github.io/Azure-Verified-Modules/) for consistency, security, and maintainability. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 318a5b12d..30acf4ac7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,7 @@ # Contributing +**Last Updated**: 2026-04-30 + Thanks for helping improve Holiday Peak Hub. This repo is a Python 3.13 monorepo with a shared micro-framework (`lib/`) plus multiple FastAPI agent services (`apps/`) and a Next.js frontend (`apps/ui/`). Keep changes small, tested, and focused. ## Prerequisites @@ -20,7 +22,7 @@ Thanks for helping improve Holiday Peak Hub. This repo is a Python 3.13 monorepo | Tool | Version | Install | |------|---------|---------| | **Azure CLI (az)** | ≥ 2.67 | [Install guide](https://learn.microsoft.com/cli/azure/install-azure-cli) | -| **Azure Developer CLI (azd)** | Latest | [Install guide](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) — used by `azure.yaml` hooks and `scripts/ops/demo-provision.ps1` | +| **Azure Developer CLI (azd)** | Latest | [Install guide](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) — used by `azure.yaml` hooks and `scripts/powershell/ops/demo-provision.ps1` | | **Azure CLI `alb` extension** | Latest | `az extension add --name alb` — required for Application Gateway for Containers (AGC) operations | ### Kubernetes tooling (for AKS deployment) @@ -28,7 +30,7 @@ Thanks for helping improve Holiday Peak Hub. This repo is a Python 3.13 monorepo | Tool | Version | Notes | |------|---------|-------| | **Helm** | 3.x | Predeploy hooks run `helm template` via `.infra/azd/hooks/render-helm.*` | -| **kubectl** | Matching AKS cluster | Required after `az aks get-credentials`; used by deploy hooks and `scripts/ops/demo-preflight-validate.ps1` | +| **kubectl** | Matching AKS cluster | Required after `az aks get-credentials`; used by deploy hooks and `scripts/powershell/ops/demo-preflight-validate.ps1` | | **kubelogin** | Latest | `az aks install-cli --kubelogin-version latest` — required for Entra ID-based AKS auth | ### Azure services (for end-to-end testing) @@ -45,7 +47,7 @@ When exercising memory/adapters end-to-end, you need access to: - **Azure AI Foundry / AI Services** (agent model endpoints) - **Azure API Management** (API gateway — deploy workflows use `az apim` commands) -> **Tip**: Use `scripts/start-dev-environment.ps1` to start stopped dev resources (PostgreSQL, AKS) that may have been paused by cost-saving automation. +> **Tip**: Use `scripts/powershell/ops/start-dev-environment.ps1` to start stopped dev resources (PostgreSQL, AKS) that may have been paused by cost-saving automation. ## Backend setup (Python) @@ -125,7 +127,7 @@ python -m pip_audit --skip-editable ```bash git config core.hooksPath .githooks ``` -With push gate enabled, every push runs `scripts/ops/pre_push_gate.py`, which mirrors the CI lint/test gate commands used by `.github/workflows/lint.yml` and `.github/workflows/test.yml`. +With push gate enabled, every push runs `scripts/python/ops/pre_push_gate.py`, which mirrors the CI lint/test gate commands used by `.github/workflows/lint.yml` and `.github/workflows/test.yml`. ### Run a service locally ```bash diff --git a/README.MD b/README.MD index 550dd98ab..461a0521e 100644 --- a/README.MD +++ b/README.MD @@ -1,6 +1,8 @@ # Holiday Peak Hub -Agent-driven retail accelerator for building and operating intelligent, cloud-native retail services with a shared framework and domain-focused apps. +> **Last Updated**: 2026-04-30 + +Agent-driven retail accelerator for building and operating intelligent, cloud-native retail services with a shared framework and domain-focused apps. **26 AI agents** orchestrate retail operations — from product discovery to returns — using Microsoft Agent Framework, Azure AI Foundry, and three-tier memory, all deployed on AKS with Flux GitOps. [![Release](https://img.shields.io/github/v/release/Azure-Samples/holiday-peak-hub?display_name=tag&include_prereleases&sort=semver)](https://github.com/Azure-Samples/holiday-peak-hub/releases) [![Pre-release](https://img.shields.io/badge/channel-unstable-orange)](https://github.com/Azure-Samples/holiday-peak-hub/releases/tag/v2.1.0-unstable.0) @@ -12,52 +14,95 @@ Agent-driven retail accelerator for building and operating intelligent, cloud-na [![Tests](https://img.shields.io/badge/tests-1796%20passed-brightgreen)](docs/project-status.md) [![License](https://img.shields.io/github/license/Azure-Samples/holiday-peak-hub)](LICENSE) +--- + +## What Is This? + +Holiday Peak Hub demonstrates how **AI agents replace static microservice logic** in retail platforms. Instead of hard-coded business rules, domain-specific agents reason over context, adapt to real-time signals, and collaborate through event choreography — delivering personalization, optimization, and intelligence that traditional architectures cannot match. + +| Dimension | Traditional Microservices | Holiday Peak Hub (Agentic) | +|-----------|--------------------------|---------------------------| +| Decision making | Static conditionals | Context-aware reasoning via LLM/SLM | +| Personalization | Rule-based segments | Real-time 1:1 personalization | +| Cross-domain coordination | Orchestrator or REST chains | Event choreography + MCP agent-to-agent | +| Adaptability | Code changes → deploy cycle | Prompt/knowledge updates + adaptive routing | + ## Architecture ![Holiday Peak Hub — Reference Architecture](docs/architecture/diagrams/holiday-peak-hub-architecture.png) -## Quick links +### Platform at a Glance + +| Layer | Technology | Purpose | +|-------|-----------|---------| +| **Agents (26)** | Python 3.13, FastAPI, MAF >=1.0.1 | Domain intelligence (CRM, eCommerce, Inventory, Logistics, Product Mgmt) | +| **CRUD Service** | Python 3.13, FastAPI, PostgreSQL | Transactional operations, REST APIs, event publishing | +| **UI** | Next.js 15, TypeScript, Tailwind | Executive demo, commerce journey, admin cockpit | +| **Gateway** | APIM + AGC | API governance, rate limiting, edge routing | +| **Models** | GPT-5-nano (SLM), GPT-4o (LLM) | SLM-first routing with LLM escalation | +| **Memory** | Redis → Cosmos DB → Blob Storage | Three-tier: hot (cache) → warm (state) → cold (archive) | +| **Events** | Azure Event Hubs (8 topics) | Saga choreography between services | +| **Search** | Azure AI Search | Vector/hybrid semantic search | +| **Deployment** | AKS + Flux CD GitOps | Declarative reconciliation, tested image promotion | +| **CI/CD** | GitHub Actions | Lint, test, CodeQL, pip-audit, deploy | + +--- + +## Quick Links + +| Audience | Start Here | +|----------|-----------| +| **Developers** | [apps/README.md](apps/README.md) — Service catalog and local run | +| **Architects** | [docs/architecture/README.md](docs/architecture/README.md) — ADRs and design | +| **Operators** | [.infra/README.md](.infra/README.md) — Provisioning and deployment | +| **Business** | [docs/architecture/business-summary.md](docs/architecture/business-summary.md) — Value proposition | +| **All** | [docs/README.md](docs/README.md) — Documentation hub | + +Additional links: [Implementation roadmap](docs/IMPLEMENTATION_ROADMAP.md) · [Changelog](CHANGELOG.md) · [27 ADRs](docs/architecture/ADRs.md) -- [Documentation hub](docs/README.md) -- [Architecture](docs/architecture/README.md) -- [Provisioning & deployment (azd)](.infra/README.md) -- [Implementation roadmap](docs/IMPLEMENTATION_ROADMAP.md) -- [Changelog](CHANGELOG.md) +--- -## Fast start (local) +## Fast Start (Local) ### Prerequisites -- Python 3.13+ -- Node.js 20+ -- Yarn -- Azure CLI and Azure Developer CLI (`azd`) -- Docker (required for `azd` deployment) +| Tool | Version | Purpose | +|------|---------|---------| +| Python | 3.13+ | Backend services | +| Node.js | 20+ | Frontend UI | +| Yarn | Latest | Frontend package manager | +| uv | Latest | Python package manager | +| Azure CLI | Latest | Azure authentication | +| azd | Latest | Azure Developer CLI | +| Docker | Latest | Container builds for deployment | -### Run locally +### Run Locally ```bash -# From repo root -python -m pip install --upgrade pip +# From repo root — install framework pip install -e lib -# Install one service (example) +# Install and run CRUD service pip install -e apps/crud-service/src - -# Run CRUD service uvicorn crud_service.main:app --reload --port 8000 --app-dir apps/crud-service/src +# Install and run an agent (separate terminal) +pip install -e apps/ecommerce-catalog-search/src +uvicorn catalog_search.main:app --reload --port 8001 --app-dir apps/ecommerce-catalog-search/src + # Run UI (separate terminal) cd apps/ui yarn install yarn dev ``` -For complete local setup across services, see [apps/README.md](apps/README.md) and [docs/backend_plan.md](docs/backend_plan.md). +For complete local setup across services, see [apps/README.md](apps/README.md). + +--- ## Provision to Azure (azd) -This is the primary path for provisioning and deployment. Be sure to have Docker running locally before running. +Primary path for provisioning and deployment. Requires Docker running locally. ```bash # 1) Sign in @@ -74,17 +119,49 @@ azd provision -e azd deploy -e ``` -For environment flags, service-scoped deploys, shared/static topology options, and CI/CD entry workflows, see [.infra/README.md](.infra/README.md) and [docs/governance/README.md](docs/governance/README.md). +For environment flags, service-scoped deploys, Flux GitOps details, and CI/CD workflows, see [.infra/README.md](.infra/README.md) and [docs/governance/README.md](docs/governance/README.md). + +--- + +## Repository Structure + +``` +├── lib/ # Shared framework (holiday_peak_lib) +├── apps/ # 26 agent services + CRUD + UI +│ ├── crud-service/ # Transactional REST API +│ ├── ui/ # Next.js 15 frontend +│ ├── crm-*/ # CRM domain agents (4) +│ ├── ecommerce-*/ # eCommerce domain agents (5) +│ ├── inventory-*/ # Inventory domain agents (4) +│ ├── logistics-*/ # Logistics domain agents (4) +│ ├── product-management-*/ # Product management agents (4) +│ ├── search-enrichment-agent/ # Search enrichment +│ └── truth-*/ # Product Truth Layer agents (4) +├── docs/ # Architecture, ADRs, governance, roadmap +├── .infra/ # Bicep infrastructure modules +├── .kubernetes/ # Flux GitOps manifests +├── .github/workflows/ # CI/CD pipelines +└── scripts/ # Automation and ops scripts +``` + +--- + +## Where to Find Everything -## Where to find everything else +| Topic | Document | +|-------|----------| +| Framework API (BaseRetailAgent, AgentBuilder, FoundryAgentInvoker) | [lib/README.md](lib/README.md) | +| All services with endpoints and domains | [apps/README.md](apps/README.md) | +| Architecture decisions (27 ADRs) | [docs/architecture/ADRs.md](docs/architecture/ADRs.md) | +| Business scenarios and value proposition | [docs/business_scenarios/README.md](docs/business_scenarios/README.md) | +| Governance and release policy | [docs/governance/README.md](docs/governance/README.md) | +| Operational runbooks | [docs/ops/](docs/ops/) | +| Security posture | [SECURITY.MD](SECURITY.MD) | +| Project status and metrics | [docs/project-status.md](docs/project-status.md) | -- Framework library: [lib/README.md](lib/README.md) -- Service catalog and app guidance: [apps/README.md](apps/README.md) -- Architecture decisions (ADRs): [docs/architecture/ADRs.md](docs/architecture/ADRs.md) -- Governance and release policy: [docs/governance/README.md](docs/governance/README.md) -- Security: [SECURITY.MD](SECURITY.MD) +--- -## Contributing and license +## Contributing and License - Contributing guide: [CONTRIBUTING.md](CONTRIBUTING.md) - License: [LICENSE](LICENSE) diff --git a/SECURITY.MD b/SECURITY.MD index cb863c955..e84ccfd76 100644 --- a/SECURITY.MD +++ b/SECURITY.MD @@ -1,27 +1,26 @@ # Security Policy +**Last Updated**: 2026-04-30 + ## Supported Versions This repository currently supports the default branch: - `main` -Use this section to tell people about which versions of your project are -currently being supported with security updates. - | Version | Supported | | ------- | ------------------ | -| 5.1.x | :white_check_mark: | -| 5.0.x | :x: | -| 4.0.x | :white_check_mark: | -| < 4.0 | :x: | +| main | :white_check_mark: | -## Reporting a Vulnerability +## Security Architecture -Use this section to tell people how to report a vulnerability. +- **Authentication**: Microsoft Entra ID with JWT validation + RBAC (4 roles: anonymous, customer, staff, admin) +- **Secrets management**: Azure Key Vault (no secrets in source or env literals) +- **Identity**: Managed Identity and Entra-based federation for deployment identities (OIDC) +- **Network**: Private Endpoints, NSGs, AGC for edge routing +- **CI scanning**: CodeQL (weekly + PR), pip-audit, Dependabot (grouped updates) +- **Governance**: Weekly security triage via `security-triage-report.yml` workflow -Tell them where to go, how often they can expect to get an update on a -reported vulnerability, what to expect if the vulnerability is accepted or -declined, etc. +## Reporting a Vulnerability Please do **not** open public issues for security reports. diff --git a/apps/README.md b/apps/README.md index c4ab69384..a38edb3c1 100644 --- a/apps/README.md +++ b/apps/README.md @@ -1,5 +1,7 @@ # Apps Directory +> Last Updated: 2026-04-30 + This directory contains the deployable Holiday Peak Hub services: - 1 transactional microservice (`crud-service`) - 26 Python agent/automation services @@ -7,37 +9,96 @@ This directory contains the deployable Holiday Peak Hub services: ## App Inventory -| App | Type | Purpose | -|---|---|---| -| `crm-campaign-intelligence` | Agent service | Generates campaign intelligence from CRM and funnel context. | -| `crm-profile-aggregation` | Agent service | Builds unified customer profiles from distributed CRM data. | -| `crm-segmentation-personalization` | Agent service | Segments customers and suggests personalization actions. | -| `crm-support-assistance` | Agent service | Produces support-assist context and recommended actions. | -| `crud-service` | Microservice | Owns transactional CRUD APIs and event publishing. | -| `ecommerce-cart-intelligence` | Agent service | Scores cart risk and recommends conversion improvements. | -| `ecommerce-catalog-search` | Agent service | Delivers catalog discovery and ACP-aligned search responses. | -| `ecommerce-checkout-support` | Agent service | Evaluates checkout blockers and completion guidance. | -| `ecommerce-order-status` | Agent service | Provides order and shipment status intelligence. | -| `ecommerce-product-detail-enrichment` | Agent service | Enriches product detail context for shopping experiences. | -| `inventory-alerts-triggers` | Agent service | Detects inventory alerts and trigger conditions. | -| `inventory-health-check` | Agent service | Assesses inventory health and anomaly signals. | -| `inventory-jit-replenishment` | Agent service | Recommends just-in-time replenishment actions. | -| `inventory-reservation-validation` | Agent service | Validates reservation requests against stock conditions. | -| `logistics-carrier-selection` | Agent service | Recommends carrier options and trade-offs. | -| `logistics-eta-computation` | Agent service | Computes ETA projections and delay risk signals. | -| `logistics-returns-support` | Agent service | Guides returns-related operational decisions. | -| `logistics-route-issue-detection` | Agent service | Detects route issues and recovery recommendations. | -| `product-management-acp-transformation` | Agent service | Transforms product data into ACP-aligned payloads. | -| `product-management-assortment-optimization` | Agent service | Ranks and optimizes assortment decisions. | -| `product-management-consistency-validation` | Agent service | Evaluates product consistency and completeness signals. | -| `product-management-normalization-classification` | Agent service | Normalizes and classifies product attributes. | -| `search-enrichment-agent` | Agent service | Enriches search-oriented product content asynchronously. | -| `truth-enrichment` | Agent service | Generates proposed truth-layer attribute enrichments. | -| `truth-export` | Agent service | Exports truth-layer attributes to downstream protocols/systems. | -| `truth-hitl` | Agent service | Supports human-in-the-loop review and approval queues. | -| `truth-ingestion` | Agent service | Ingests source product data into truth workflows. | -| `ui` | Frontend | Next.js portal for admin, operations, and retail workflows. | - -## Common Service Pattern - -Most Python app services are FastAPI services built with `build_service_app`, exposing synchronous interfaces and background Event Hub processing. Configuration is environment-driven, including Foundry model settings and optional Redis/Cosmos/Blob memory tiers. +| App | Type | Bounded Context | Purpose | Event Hub Subscriptions | +|-----|------|----------------|---------|------------------------| +| `crm-campaign-intelligence` | Agent | CRM | Generates campaign intelligence from CRM and funnel context | `user-events`, `order-events`, `payment-events` | +| `crm-profile-aggregation` | Agent | CRM | Builds unified customer profiles from distributed CRM data | `user-events`, `order-events` | +| `crm-segmentation-personalization` | Agent | CRM | Segments customers and suggests personalization actions | `order-events` | +| `crm-support-assistance` | Agent | CRM | Produces support-assist context and recommended actions | `order-events`, `return-events` | +| `crud-service` | Microservice | Platform | Owns transactional CRUD APIs and publishes domain events to 7 Event Hub topics | N/A (publisher) | +| `ecommerce-cart-intelligence` | Agent | eCommerce | Scores cart risk and recommends conversion improvements | `order-events` | +| `ecommerce-catalog-search` | Agent | eCommerce | Delivers catalog discovery via Azure AI Search with intent-grounding | `product-events` | +| `ecommerce-checkout-support` | Agent | eCommerce | Evaluates checkout blockers and completion guidance | `order-events`, `inventory-events` | +| `ecommerce-order-status` | Agent | eCommerce | Provides order and shipment status intelligence | `order-events`, `shipment-events` | +| `ecommerce-product-detail-enrichment` | Agent | eCommerce | Enriches product detail context for shopping experiences | `product-events` | +| `inventory-alerts-triggers` | Agent | Inventory | Detects inventory alerts and trigger conditions | `inventory-events` | +| `inventory-health-check` | Agent | Inventory | Assesses inventory health and anomaly signals | `order-events`, `inventory-events` | +| `inventory-jit-replenishment` | Agent | Inventory | Recommends just-in-time replenishment actions | `inventory-events` | +| `inventory-reservation-validation` | Agent | Inventory | Validates reservation requests against stock conditions | `order-events` | +| `logistics-carrier-selection` | Agent | Logistics | Recommends carrier options and trade-offs | `order-events`, `shipment-events` | +| `logistics-eta-computation` | Agent | Logistics | Computes ETA projections and delay risk signals | `order-events`, `shipment-events` | +| `logistics-returns-support` | Agent | Logistics | Guides returns-related operational decisions | `order-events`, `return-events` | +| `logistics-route-issue-detection` | Agent | Logistics | Detects route issues and recovery recommendations | `order-events` | +| `product-management-acp-transformation` | Agent | Product Management | Transforms product data into ACP-aligned payloads | `product-events` | +| `product-management-assortment-optimization` | Agent | Product Management | Ranks and optimizes assortment decisions | `order-events`, `product-events` | +| `product-management-consistency-validation` | Agent | Product Management | Evaluates product consistency and completeness signals | `completeness-jobs` (platform) | +| `product-management-normalization-classification` | Agent | Product Management | Normalizes and classifies product attributes | `product-events` | +| `search-enrichment-agent` | Agent | Search | Enriches search-oriented product content asynchronously | `search-enrichment-jobs` (platform) | +| `truth-enrichment` | Agent | Truth Layer | Generates proposed truth-layer attribute enrichments | `enrichment-jobs` (platform) | +| `truth-export` | Agent | Truth Layer | Exports truth-layer attributes to downstream protocols/systems | `export-jobs` (platform) | +| `truth-hitl` | Agent | Truth Layer | Supports human-in-the-loop review and approval queues | `hitl-jobs` (platform) | +| `truth-ingestion` | Agent | Truth Layer | Ingests source product data into truth workflows | `ingest-jobs` (platform) | +| `ui` | Frontend | Portal | Next.js 15 portal for admin, operations, and retail workflows | N/A | + +## Common Agent Service Pattern + +All 26 Python agent services follow the same structural pattern using `create_standard_app` from `holiday_peak_lib`: + +```python +from holiday_peak_lib import create_standard_app +from holiday_peak_lib.utils import EventHubSubscription +from my_service.agents import MyAgent, register_mcp_tools +from my_service.event_handlers import build_event_handlers + +SERVICE_NAME = "my-service-name" +app = create_standard_app( + require_foundry_readiness=True, + disable_tracing_without_foundry=True, + service_name=SERVICE_NAME, + agent_class=MyAgent, + mcp_setup=register_mcp_tools, + subscriptions=[EventHubSubscription("topic-events", "consumer-group")], + handlers=build_event_handlers(), +) +``` + +### Standard Endpoints (all agents) + +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe (includes Foundry connectivity) | +| GET | `/self-healing/status` | Self-healing kernel state | +| GET | `/self-healing/incidents` | Active incident list | +| POST | `/self-healing/reconcile` | Trigger manual reconciliation | +| * | `/mcp/*` | MCP tool endpoints (agent-to-agent) | + +### Technology Stack + +- **Runtime**: Python 3.13, FastAPI, uvicorn +- **Package manager**: `uv` +- **AI Runtime**: Microsoft Agent Framework (MAF) >=1.0.1 GA +- **Model Routing**: GPT-5-nano (SLM/fast) → GPT-4o (LLM/rich) +- **Memory**: Redis (hot) / Cosmos DB (warm) / Blob Storage (cold) +- **Events**: Azure Event Hubs (8 topics) +- **Agent Protocol**: MCP via `FastAPIMCPServer` +- **Observability**: OpenTelemetry → Azure Monitor + +## Event Hub Topics + +| Topic | Publisher | Subscribers | +|-------|----------|-------------| +| `order-events` | CRUD Service | 11 agents | +| `payment-events` | CRUD Service | 1 agent | +| `return-events` | CRUD Service | 2 agents | +| `inventory-events` | CRUD Service | 4 agents | +| `shipment-events` | CRUD Service | 3 agents | +| `product-events` | CRUD Service | 4 agents | +| `user-events` | CRUD Service | 2 agents | +| `enrichment-jobs` | Platform/HITL | 1 agent (truth-enrichment) | +| `export-jobs` | Platform/HITL | 1 agent (truth-export) | +| `hitl-jobs` | Platform | 1 agent (truth-hitl) | +| `ingest-jobs` | Platform | 1 agent (truth-ingestion) | +| `completeness-jobs` | Platform | 1 agent (consistency-validation) | +| `search-enrichment-jobs` | Platform/HITL | 1 agent (search-enrichment-agent) | diff --git a/apps/crm-campaign-intelligence/README.md b/apps/crm-campaign-intelligence/README.md index 0ef73679e..881e70b88 100644 --- a/apps/crm-campaign-intelligence/README.md +++ b/apps/crm-campaign-intelligence/README.md @@ -1,32 +1,72 @@ # CRM Campaign Intelligence -## Purpose -Provides campaign intelligence by combining CRM context with campaign and funnel signals. - -## Responsibilities -- Analyze campaign performance patterns. -- Surface likely drop-off and conversion risk points. -- Return recommendations to improve campaign outcomes. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Generates campaign intelligence insights by combining CRM contact context with campaign and funnel signals. Analyzes performance patterns, surfaces drop-off and conversion risk points, and returns recommendations to improve campaign outcomes. + +## Domain Bounded Context +- **Owner**: CRM team +- **Bounded Context**: CRM + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation with campaign query | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe (Foundry connectivity) | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/campaign/contact-context` | Retrieve CRM contact context with interaction history | +| `/campaign/funnel-context` | Retrieve funnel metrics for a campaign/account | +| `/campaign/roi` | Estimate campaign ROI from funnel data and spend | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `user-events` | `campaign-intel-group` | React to user lifecycle changes | +| `order-events` | `campaign-intel-group` | Incorporate order signals into campaign analysis | +| `payment-events` | `campaign-intel-group` | Track payment outcomes for ROI | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------| +| Hot (Redis) | Cached campaign intelligence results (TTL 300s) | +| Warm (Cosmos DB) | Campaign session history | +| Cold (Blob) | Long-term campaign performance archives | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/crm-campaign-intelligence/src uv sync -uv run uvicorn crm_campaign_intelligence.main:app --reload -python -m pytest ../tests +uv run uvicorn crm_campaign_intelligence.main:app --reload --port 8001 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. - ---- +## Test Coverage +```bash +python -m pytest apps/crm-campaign-intelligence/tests +``` ## Standalone Deployment - azd-first (ACR -> AKS) diff --git a/apps/crm-profile-aggregation/README.md b/apps/crm-profile-aggregation/README.md index f3214059d..6e76eeba9 100644 --- a/apps/crm-profile-aggregation/README.md +++ b/apps/crm-profile-aggregation/README.md @@ -1,30 +1,71 @@ # CRM Profile Aggregation -## Purpose -Builds a unified customer profile from distributed CRM and interaction sources. - -## Responsibilities -- Aggregate identity, contact, and engagement context. -- Resolve profile-level signals for downstream decisioning. -- Provide a consistent profile view for other services. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Builds unified customer profiles by aggregating identity, contact, and engagement context from distributed CRM and interaction sources. Resolves profile-level signals for downstream decisioning agents. + +## Domain Bounded Context +- **Owner**: CRM team +- **Bounded Context**: CRM + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/profile/contact-context` | Retrieve full contact context with interactions | +| `/profile/summary` | AI-generated profile summary | +| `/profile/account-summary` | Account-level aggregation | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `user-events` | `profile-agg-group` | Update profile on user changes | +| `order-events` | `profile-agg-group` | Incorporate purchase history | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached profile lookups (TTL 300s) | +| Warm (Cosmos DB) | Aggregated profile state | +| Cold (Blob) | Historical profile snapshots | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/crm-profile-aggregation/src uv sync -uv run uvicorn crm_profile_aggregation.main:app --reload -python -m pytest ../tests +uv run uvicorn crm_profile_aggregation.main:app --reload --port 8002 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/crm-profile-aggregation/tests +``` --- diff --git a/apps/crm-segmentation-personalization/README.md b/apps/crm-segmentation-personalization/README.md index 8902b28c2..0204e4f4d 100644 --- a/apps/crm-segmentation-personalization/README.md +++ b/apps/crm-segmentation-personalization/README.md @@ -1,30 +1,69 @@ -# CRM Segmentation Personalization +# CRM Segmentation & Personalization -## Purpose -Segments customers and proposes personalization actions based on customer context. - -## Responsibilities -- Classify users into actionable engagement segments. -- Generate channel and content personalization guidance. -- Provide explainable segment-level recommendations. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Segments customers into actionable engagement groups and proposes personalization actions. Generates channel and content guidance with explainable segment-level recommendations. + +## Domain Bounded Context +- **Owner**: CRM team +- **Bounded Context**: CRM + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/segmentation/context` | Retrieve segmentation context for a customer | +| `/segmentation/personalize` | Generate personalization recommendations | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `order-events` | `segmentation-group` | Update segments on purchase behavior | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached segment assignments (TTL 300s) | +| Warm (Cosmos DB) | Segment history and personalization state | +| Cold (Blob) | Long-term segmentation analytics | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/crm-segmentation-personalization/src uv sync -uv run uvicorn crm_segmentation_personalization.main:app --reload -python -m pytest ../tests +uv run uvicorn crm_segmentation_personalization.main:app --reload --port 8003 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/crm-segmentation-personalization/tests +``` --- diff --git a/apps/crm-support-assistance/README.md b/apps/crm-support-assistance/README.md index f91bc91fd..6fe115761 100644 --- a/apps/crm-support-assistance/README.md +++ b/apps/crm-support-assistance/README.md @@ -1,30 +1,70 @@ # CRM Support Assistance -## Purpose -Produces support-facing assistance with CRM context and next-best-action recommendations. - -## Responsibilities -- Assemble customer context for support interactions. -- Identify sentiment and escalation risk cues. -- Suggest prioritized response actions. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Produces support-facing assistance by assembling customer context from CRM, identifying sentiment and escalation risk cues, and suggesting prioritized next-best-action recommendations. + +## Domain Bounded Context +- **Owner**: CRM team +- **Bounded Context**: CRM + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/support/context` | Retrieve support context for a customer | +| `/support/recommendations` | AI-generated next-best-action suggestions | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `order-events` | `support-group` | Track order issues for support context | +| `return-events` | `support-group` | Incorporate return signals | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached support context (TTL 300s) | +| Warm (Cosmos DB) | Support interaction history | +| Cold (Blob) | Historical support case archives | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/crm-support-assistance/src uv sync -uv run uvicorn crm_support_assistance.main:app --reload -python -m pytest ../tests +uv run uvicorn crm_support_assistance.main:app --reload --port 8004 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/crm-support-assistance/tests +``` --- diff --git a/apps/crud-service/README.md b/apps/crud-service/README.md index b6ec75c03..c806bb76e 100644 --- a/apps/crud-service/README.md +++ b/apps/crud-service/README.md @@ -1,30 +1,136 @@ # CRUD Service +> Last Updated: 2026-04-30 + ## Purpose -Provides the transactional FastAPI microservice for Holiday Peak Hub domain operations. + +The transactional FastAPI microservice that owns all CRUD operations for Holiday Peak Hub. This is **not** an agent service — it is a pure REST API for deterministic, transactional data operations (orders, products, users, cart, payments, inventory, returns) and the sole publisher of domain events to Azure Event Hubs consumed by 26 agent services. + +## Domain Bounded Context +- **Owner**: Platform team +- **Bounded Context**: Transactional platform (cross-domain data ownership) ## Responsibilities -- Own customer, catalog, cart, order, payment, and operational CRUD workflows. -- Expose API surfaces used by frontend and service integrations. -- Publish domain events consumed by asynchronous agent services. -- Compose routes through bounded groups (`platform`, `commerce`, `staff`, `truth`) while preserving existing API paths. -- Treat connector bootstrap as optional runtime wiring when connector domains are configured. - -## Key endpoints or interfaces -- Root and health endpoints: `GET /`, `GET /health`, `GET /ready`. -- Primary API namespaces under `/api/*` (auth, users, products, cart, orders, inventory, payments, staff, truth). -- ACP endpoints under `/acp/*` (products, checkout, and delegated payment paths). -- Webhook endpoints for Stripe and connector integrations. - -## Run/Test commands +- Own customer, catalog, cart, order, payment, inventory, returns, and operational CRUD workflows +- Expose REST API surfaces consumed by the Next.js frontend and agent services +- Publish domain events to 7 Event Hub topics consumed by asynchronous agent services +- Compose routes through bounded groups (`platform`, `commerce`, `staff`, `truth`) +- Provide ACP (Akeneo Connector Protocol) and UCP (Unified Commerce Protocol) endpoints +- Manage Truth Layer persistence (attributes, proposals, completeness, audit trail) +- Treat connector bootstrap as optional runtime wiring when connector domains are configured + +## Endpoints + +### Platform Routes + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/` | Root status | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe (DB pool, event publisher) | +| POST | `/api/auth/register` | User registration | +| POST | `/api/auth/login` | User authentication | +| POST | `/api/auth/refresh` | Token refresh | +| * | `/api/users/*` | User CRUD | +| POST | `/webhooks/stripe` | Stripe webhook receiver | +| POST | `/webhooks/connectors/*` | Connector integration webhooks | + +### Commerce Routes + +| Method | Path | Description | +|--------|------|-------------| +| GET/POST/PUT/DELETE | `/api/products/*` | Product catalog CRUD | +| GET/POST | `/api/categories/*` | Product category management | +| GET/POST/PUT/DELETE | `/api/cart/*` | Shopping cart operations | +| GET/POST/PUT | `/api/orders/*` | Order lifecycle management | +| GET/POST | `/api/inventory/*` | Inventory levels and reservations | +| POST | `/api/checkout/*` | Checkout flow | +| POST | `/api/payments/*` | Payment processing | +| GET/POST/PUT | `/api/returns/*` | Customer returns lifecycle | +| GET/POST | `/api/reviews/*` | Product reviews | +| GET | `/api/brand-shopping/*` | Brand-filtered shopping | +| GET/POST | `/acp/products/*` | ACP product endpoints | +| POST | `/acp/checkout/*` | ACP checkout | +| POST | `/acp/payments/*` | ACP payment delegation | + +### Truth Layer Routes + +| Method | Path | Description | +|--------|------|-------------| +| GET/POST/PUT | `/api/truth-attributes/*` | Truth attribute management | +| GET/POST/PUT | `/api/proposed-attributes/*` | Enrichment proposal CRUD | +| GET | `/api/schemas-registry/*` | Schema registry for truth layer | +| GET | `/api/completeness/*` | Product completeness scoring | +| GET | `/api/audit-trail/*` | Enrichment and approval audit logs | +| GET | `/api/ucp-products/*` | UCP product views | + +### Staff Routes + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/api/staff/analytics/*` | Staff analytics dashboards | +| GET/POST/PUT | `/api/staff/tickets/*` | Support ticket management | +| GET/POST/PUT | `/api/staff/returns/*` | Staff returns processing | +| GET/POST | `/api/staff/shipments/*` | Shipment management | + +## Event Hub Publications + +The CRUD service publishes domain events to these topics: + +| Topic | Events Published | Triggered By | +|-------|-----------------|--------------| +| `order-events` | `OrderCreated`, `OrderUpdated`, `OrderCancelled` | Order lifecycle mutations | +| `payment-events` | `PaymentProcessed`, `PaymentFailed`, `RefundIssued` | Payment processing | +| `return-events` | `ReturnRequested`, `ReturnApproved`, `ReturnRejected`, `ReturnReceived`, `ReturnRestocked`, `ReturnRefunded` | Returns lifecycle | +| `inventory-events` | `InventoryReserved`, `InventoryReleased` | Reservation/release operations | +| `shipment-events` | `ShipmentCreated`, `ShipmentUpdated` | Shipment mutations | +| `product-events` | `ProductCreated`, `ProductUpdated`, `ProductDeleted` | Product catalog changes | +| `user-events` | `UserRegistered`, `UserUpdated` | User lifecycle | + +All events are published with: +- Correlation ID propagation for distributed tracing +- Critical saga reliability profiles (retries + dead-letter) +- Self-healing kernel integration for publish failure detection + +## Architecture Notes + +- **No agent logic**: This is a pure microservice — no `BaseRetailAgent`, no model invocation +- **PostgreSQL**: Primary data store via `asyncpg` connection pool +- **Entra ID / password auth**: Dual authentication mode for PostgreSQL +- **Key Vault integration**: Secrets resolved at startup for DB and Redis passwords +- **Connector registry**: Optional enterprise connector bootstrap (PIM, DAM, CRM domains) +- **Connector sync consumer**: Listens for connector-originated data sync events +- **OpenTelemetry**: Optional Azure Monitor/Application Insights instrumentation + +## Environment Variables + +| Variable | Required | Description | +|----------|----------|-------------| +| `POSTGRES_HOST` | Yes | PostgreSQL server hostname | +| `POSTGRES_DATABASE` | Yes | Database name | +| `POSTGRES_USER` | Yes | Database user | +| `POSTGRES_PASSWORD` | No | DB password (resolved from Key Vault if not set) | +| `POSTGRES_AUTH_MODE` | No | `password` or `entra` (default: `password`) | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace for domain event publishing | +| `REDIS_HOST` | No | Redis cache hostname | +| `REDIS_PASSWORD` | No | Redis password (resolved from Key Vault) | +| `KEY_VAULT_URI` | No | Azure Key Vault URI for secret resolution | +| `APP_INSIGHTS_CONNECTION_STRING` | No | Application Insights connection | +| `CONNECTOR_ENABLED_DOMAINS` | No | Comma-separated connector domains to bootstrap | +| `CONNECTOR_HEALTH_INTERVAL_SECONDS` | No | Health monitor interval (default: 60) | + +## Local Development + ```bash cd apps/crud-service/src uv sync -uv run uvicorn crud_service.main:app --reload -python -m pytest ../tests +uv run uvicorn crud_service.main:app --reload --port 8000 +``` + +## Test Coverage + +```bash +python -m pytest apps/crud-service/tests ``` -## Configuration notes -- Uses PostgreSQL settings, auth settings, and Event Hub publisher configuration from environment variables. -- Supports Entra/password database auth modes and optional Key Vault secret resolution. -- Includes optional telemetry and connector settings for operational integration. +Test files located in `apps/crud-service/tests/`. diff --git a/apps/ecommerce-cart-intelligence/README.md b/apps/ecommerce-cart-intelligence/README.md index a5c975bf5..ce66e8737 100644 --- a/apps/ecommerce-cart-intelligence/README.md +++ b/apps/ecommerce-cart-intelligence/README.md @@ -1,30 +1,69 @@ # Ecommerce Cart Intelligence -## Purpose -Analyzes carts to identify friction, abandonment risk, and conversion opportunities. - -## Responsibilities -- Score cart-level conversion risk signals. -- Detect likely blockers in price, inventory, or composition. -- Recommend actions to improve checkout completion. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Analyzes shopping carts to identify friction, abandonment risk, and conversion opportunities. Scores cart-level risk signals and recommends actions to improve checkout completion. + +## Domain Bounded Context +- **Owner**: eCommerce team +- **Bounded Context**: eCommerce + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/cart/context` | Build full cart context with product, pricing, and inventory | +| `/cart/abandonment-risk` | Estimate cart abandonment risk score | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `order-events` | `cart-intel-group` | React to order patterns for cart scoring | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached cart analysis results (TTL 300s) | +| Warm (Cosmos DB) | Cart session state | +| Cold (Blob) | Historical cart abandonment data | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/ecommerce-cart-intelligence/src uv sync -uv run uvicorn ecommerce_cart_intelligence.main:app --reload -python -m pytest ../tests +uv run uvicorn ecommerce_cart_intelligence.main:app --reload --port 8005 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/ecommerce-cart-intelligence/tests +``` --- diff --git a/apps/ecommerce-catalog-search/README.md b/apps/ecommerce-catalog-search/README.md index 80c420fbc..d4cc80723 100644 --- a/apps/ecommerce-catalog-search/README.md +++ b/apps/ecommerce-catalog-search/README.md @@ -1,38 +1,80 @@ # Ecommerce Catalog Search -## Purpose - -Provides product discovery and ACP-aligned catalog search responses. - -## Responsibilities - -- Resolve search queries into relevant product sets. -- Default to intelligent search mode when no mode is specified, while keeping explicit keyword mode available for demos and compatibility. -- Return inventory-aware and commerce-ready product context. -- Support intelligent search enrichment for downstream flows. -- Emit explicit degraded fallback metadata (`result_type`, `degraded_reason`, `fallback_keywords`) when model synthesis times out or fails. -- Uses generic intent classification with model-first evaluation and deterministic fallback. -- Runs a full retrieval cycle (baseline keyword retrieval, intent-driven query expansion, semantic retrieval, and fallback rerank) to return relevant results. - -## Key endpoints or interfaces +> Last Updated: 2026-04-30 -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription: `product-events` / consumer group `catalog-search-group`. +## Purpose -## Run/Test commands +Provides product discovery and ACP-aligned catalog search responses powered by Azure AI Search. Runs a full retrieval cycle: baseline keyword retrieval, intent-driven query expansion, semantic retrieval, and fallback rerank. + +## Domain Bounded Context +- **Owner**: eCommerce team +- **Bounded Context**: eCommerce + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation (search query) | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe (includes AI Search index readiness) | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/catalog/search` | Execute catalog search with intent classification | +| `/catalog/product-context` | Retrieve enriched product context by SKU | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `product-events` | `catalog-search-group` | React to product catalog changes | + +## Architecture Notes +- **No CRUD service calls** — product read path is Azure AI Search only +- AI Search index population is owned by `search-enrichment-agent` (async, Event Hub driven) +- Supports `intelligent` (default) and `keyword` search modes +- Emits degraded fallback metadata when model synthesis fails +- Uses generic intent classification with model-first evaluation and deterministic fallback + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` +- `keyword` mode never performs model response synthesis + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached search results (TTL 300s) | +| Warm (Cosmos DB) | Search history and intent patterns | +| Cold (Blob) | Search analytics archives | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `AI_SEARCH_ENDPOINT` | Yes | Azure AI Search endpoint | +| `AI_SEARCH_INDEX_NAME` | Yes | Search index name | +| `AI_SEARCH_REQUIRED` | No | Strict mode for readiness (default: false) | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | +## Local Development ```bash cd apps/ecommerce-catalog-search/src uv sync -uv run uvicorn ecommerce_catalog_search.main:app --reload -python -m pytest ../tests +uv run uvicorn ecommerce_catalog_search.main:app --reload --port 8006 ``` -## Configuration notes - -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- `keyword` mode never performs model response synthesis, even when Foundry models are configured. +## Test Coverage +```bash +python -m pytest apps/ecommerce-catalog-search/tests +``` - Supports Redis/Cosmos/Blob memory configuration via shared memory settings. - Requires Event Hub namespace and consumer configuration for background jobs. - Uses strict AI Search runtime mode by default on AKS unless `CATALOG_SEARCH_REQUIRE_AI_SEARCH` is explicitly overridden. diff --git a/apps/ecommerce-checkout-support/README.md b/apps/ecommerce-checkout-support/README.md index f913377db..90c3116be 100644 --- a/apps/ecommerce-checkout-support/README.md +++ b/apps/ecommerce-checkout-support/README.md @@ -1,30 +1,70 @@ # Ecommerce Checkout Support -## Purpose -Evaluates checkout flows and surfaces guidance to reduce checkout failures. - -## Responsibilities -- Detect checkout blockers across inventory, payment, and order context. -- Return actionable guidance for completion paths. -- Support real-time checkout assistance workflows. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Evaluates checkout flows to detect blockers across inventory, payment, and order context. Returns actionable guidance for completion paths and supports real-time checkout assistance workflows. + +## Domain Bounded Context +- **Owner**: eCommerce team +- **Bounded Context**: eCommerce + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/checkout/context` | Build checkout context with blockers | +| `/checkout/guidance` | Generate checkout completion guidance | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `order-events` | `checkout-group` | Track order flow for checkout analysis | +| `inventory-events` | `checkout-group` | Monitor stock for checkout blockers | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached checkout analysis (TTL 300s) | +| Warm (Cosmos DB) | Checkout session state | +| Cold (Blob) | Checkout failure archives | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/ecommerce-checkout-support/src uv sync -uv run uvicorn ecommerce_checkout_support.main:app --reload -python -m pytest ../tests +uv run uvicorn ecommerce_checkout_support.main:app --reload --port 8007 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/ecommerce-checkout-support/tests +``` --- diff --git a/apps/ecommerce-order-status/README.md b/apps/ecommerce-order-status/README.md index 9b6bee4c8..e88bfbb16 100644 --- a/apps/ecommerce-order-status/README.md +++ b/apps/ecommerce-order-status/README.md @@ -1,30 +1,70 @@ # Ecommerce Order Status -## Purpose -Provides intelligent order and shipment status interpretation for customer-facing workflows. - -## Responsibilities -- Consolidate status timeline signals for orders. -- Identify delay and exception indicators. -- Return concise status guidance and next actions. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Provides intelligent order and shipment status interpretation for customer-facing workflows. Consolidates status timeline signals, identifies delay and exception indicators, and returns concise guidance with next actions. + +## Domain Bounded Context +- **Owner**: eCommerce team +- **Bounded Context**: eCommerce + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/order/status-context` | Retrieve order status with timeline | +| `/order/delay-risk` | Assess delay risk for an order | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `order-events` | `order-status-group` | Track order lifecycle changes | +| `shipment-events` | `order-status-group` | Incorporate shipment updates | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached order status lookups (TTL 300s) | +| Warm (Cosmos DB) | Order tracking state | +| Cold (Blob) | Historical order analytics | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/ecommerce-order-status/src uv sync -uv run uvicorn ecommerce_order_status.main:app --reload -python -m pytest ../tests +uv run uvicorn ecommerce_order_status.main:app --reload --port 8008 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/ecommerce-order-status/tests +``` --- diff --git a/apps/ecommerce-product-detail-enrichment/README.md b/apps/ecommerce-product-detail-enrichment/README.md index 3caecd3c0..7f744c4db 100644 --- a/apps/ecommerce-product-detail-enrichment/README.md +++ b/apps/ecommerce-product-detail-enrichment/README.md @@ -1,30 +1,69 @@ # Ecommerce Product Detail Enrichment -## Purpose -Enriches product detail context to improve product understanding and conversion readiness. - -## Responsibilities -- Aggregate detail-page context from product and related signals. -- Identify missing or weak product detail attributes. -- Return enrichment guidance for product presentation quality. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Enriches product detail context by aggregating signals from product catalog, related items, and domain context. Identifies missing or weak attributes and returns enrichment guidance to improve presentation quality and conversion readiness. + +## Domain Bounded Context +- **Owner**: eCommerce team +- **Bounded Context**: eCommerce + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/product-detail/context` | Build enriched product detail context | +| `/product-detail/gaps` | Identify attribute gaps for a product | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `product-events` | `enrichment-group` | React to product catalog changes | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached enrichment results (TTL 300s) | +| Warm (Cosmos DB) | Product enrichment state | +| Cold (Blob) | Enrichment history archives | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/ecommerce-product-detail-enrichment/src uv sync -uv run uvicorn ecommerce_product_detail_enrichment.main:app --reload -python -m pytest ../tests +uv run uvicorn ecommerce_product_detail_enrichment.main:app --reload --port 8009 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/ecommerce-product-detail-enrichment/tests +``` --- diff --git a/apps/inventory-alerts-triggers/README.md b/apps/inventory-alerts-triggers/README.md index a9bf38957..579cdbe3f 100644 --- a/apps/inventory-alerts-triggers/README.md +++ b/apps/inventory-alerts-triggers/README.md @@ -1,30 +1,69 @@ -# Inventory Alerts Triggers +# Inventory Alerts & Triggers -## Purpose -Detects inventory alert conditions and emits actionable trigger guidance. - -## Responsibilities -- Identify low-stock and pressure scenarios. -- Evaluate urgency and likely operational impact. -- Return recommended trigger actions for inventory operations. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Detects inventory alert conditions (low-stock, pressure scenarios) and emits actionable trigger guidance. Evaluates urgency and likely operational impact to recommend trigger actions for inventory operations. + +## Domain Bounded Context +- **Owner**: Inventory team +- **Bounded Context**: Inventory + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/inventory/alerts/context` | Retrieve inventory context for a SKU | +| `/inventory/alerts` | Get active alerts with configurable threshold | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `inventory-events` | `alerts-group` | React to inventory level changes | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached alert states (TTL 300s) | +| Warm (Cosmos DB) | Alert history and thresholds | +| Cold (Blob) | Long-term alert archives | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/inventory-alerts-triggers/src uv sync -uv run uvicorn inventory_alerts_triggers.main:app --reload -python -m pytest ../tests +uv run uvicorn inventory_alerts_triggers.main:app --reload --port 8010 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/inventory-alerts-triggers/tests +``` --- diff --git a/apps/inventory-health-check/README.md b/apps/inventory-health-check/README.md index c3622ff89..ee0e17b3e 100644 --- a/apps/inventory-health-check/README.md +++ b/apps/inventory-health-check/README.md @@ -1,30 +1,70 @@ # Inventory Health Check -## Purpose -Assesses inventory quality and health signals for operational monitoring. - -## Responsibilities -- Evaluate inventory consistency and anomaly patterns. -- Surface health signals relevant to availability planning. -- Return remediation guidance for detected issues. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Assesses inventory quality and health signals for operational monitoring. Evaluates consistency and anomaly patterns, surfaces health signals relevant to availability planning, and returns remediation guidance. + +## Domain Bounded Context +- **Owner**: Inventory team +- **Bounded Context**: Inventory + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/inventory/health/context` | Retrieve inventory health context for a SKU | +| `/inventory/health/assessment` | AI-generated health assessment | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `order-events` | `health-check-group` | Factor order velocity into health | +| `inventory-events` | `health-check-group` | React to inventory level changes | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached health assessments (TTL 300s) | +| Warm (Cosmos DB) | Health trend data | +| Cold (Blob) | Historical health archives | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/inventory-health-check/src uv sync -uv run uvicorn inventory_health_check.main:app --reload -python -m pytest ../tests +uv run uvicorn inventory_health_check.main:app --reload --port 8011 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/inventory-health-check/tests +``` --- diff --git a/apps/inventory-jit-replenishment/README.md b/apps/inventory-jit-replenishment/README.md index 9ca5c5675..cf09aa761 100644 --- a/apps/inventory-jit-replenishment/README.md +++ b/apps/inventory-jit-replenishment/README.md @@ -1,30 +1,69 @@ # Inventory JIT Replenishment -## Purpose -Recommends just-in-time replenishment actions for inventory continuity. - -## Responsibilities -- Evaluate demand and stock posture. -- Suggest timing and quantity for replenishment actions. -- Provide rationale for replenishment prioritization. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Recommends just-in-time replenishment actions for inventory continuity. Evaluates demand signals and stock posture to suggest timing, quantity, and prioritization rationale for replenishment. + +## Domain Bounded Context +- **Owner**: Inventory team +- **Bounded Context**: Inventory + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/inventory/replenishment/context` | Retrieve replenishment context for a SKU | +| `/inventory/replenishment/recommend` | Generate replenishment recommendation | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `inventory-events` | `replenishment-group` | React to stock level changes | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached replenishment recommendations (TTL 300s) | +| Warm (Cosmos DB) | Demand history and replenishment state | +| Cold (Blob) | Long-term replenishment analytics | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/inventory-jit-replenishment/src uv sync -uv run uvicorn inventory_jit_replenishment.main:app --reload -python -m pytest ../tests +uv run uvicorn inventory_jit_replenishment.main:app --reload --port 8012 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/inventory-jit-replenishment/tests +``` --- diff --git a/apps/inventory-reservation-validation/README.md b/apps/inventory-reservation-validation/README.md index 20c30989e..ed5c46c5d 100644 --- a/apps/inventory-reservation-validation/README.md +++ b/apps/inventory-reservation-validation/README.md @@ -1,30 +1,69 @@ # Inventory Reservation Validation -## Purpose -Validates inventory reservations against stock constraints and fulfillment feasibility. - -## Responsibilities -- Validate requested reservation quantities. -- Detect conflicts and over-allocation conditions. -- Return validation outcomes and alternatives when applicable. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Validates inventory reservations against stock constraints and fulfillment feasibility. Detects conflicts and over-allocation conditions, returning validation outcomes and alternatives when applicable. + +## Domain Bounded Context +- **Owner**: Inventory team +- **Bounded Context**: Inventory + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/inventory/reservation/validate` | Validate a reservation request | +| `/inventory/reservation/context` | Retrieve reservation context for a SKU | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `order-events` | `reservation-group` | Validate reservations on order creation | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached validation results (TTL 300s) | +| Warm (Cosmos DB) | Reservation state and conflict history | +| Cold (Blob) | Historical reservation analytics | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/inventory-reservation-validation/src uv sync -uv run uvicorn inventory_reservation_validation.main:app --reload -python -m pytest ../tests +uv run uvicorn inventory_reservation_validation.main:app --reload --port 8013 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/inventory-reservation-validation/tests +``` --- diff --git a/apps/logistics-carrier-selection/README.md b/apps/logistics-carrier-selection/README.md index 6faff5431..4f95ab3aa 100644 --- a/apps/logistics-carrier-selection/README.md +++ b/apps/logistics-carrier-selection/README.md @@ -1,30 +1,70 @@ # Logistics Carrier Selection -## Purpose -Recommends carrier options based on shipment requirements and constraints. - -## Responsibilities -- Evaluate candidate carriers for a shipment. -- Compare trade-offs such as service level and risk. -- Return the recommended carrier decision context. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Recommends carrier options based on shipment requirements and constraints. Evaluates candidate carriers, compares trade-offs (service level, cost, risk), and returns the recommended carrier decision context. + +## Domain Bounded Context +- **Owner**: Logistics team +- **Bounded Context**: Logistics + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/logistics/carrier/context` | Retrieve carrier selection context | +| `/logistics/carrier/recommend` | Generate carrier recommendation | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `order-events` | `carrier-group` | Select carrier on new orders | +| `shipment-events` | `carrier-group` | Re-evaluate on shipment changes | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached carrier recommendations (TTL 300s) | +| Warm (Cosmos DB) | Carrier performance history | +| Cold (Blob) | Historical carrier analytics | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/logistics-carrier-selection/src uv sync -uv run uvicorn logistics_carrier_selection.main:app --reload -python -m pytest ../tests +uv run uvicorn logistics_carrier_selection.main:app --reload --port 8014 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/logistics-carrier-selection/tests +``` --- diff --git a/apps/logistics-eta-computation/README.md b/apps/logistics-eta-computation/README.md index bcd548f52..7b8b7dc12 100644 --- a/apps/logistics-eta-computation/README.md +++ b/apps/logistics-eta-computation/README.md @@ -1,30 +1,70 @@ # Logistics ETA Computation -## Purpose -Computes ETA projections and delay-risk indicators for logistics workflows. - -## Responsibilities -- Estimate shipment arrival windows. -- Detect signals that reduce ETA confidence. -- Return ETA updates with concise risk context. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Computes ETA projections and delay-risk indicators for logistics workflows. Estimates shipment arrival windows, detects signals that reduce ETA confidence, and returns updates with concise risk context. + +## Domain Bounded Context +- **Owner**: Logistics team +- **Bounded Context**: Logistics + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/logistics/eta/context` | Retrieve ETA computation context | +| `/logistics/eta/compute` | Compute ETA with risk assessment | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `order-events` | `eta-group` | Compute initial ETA on order creation | +| `shipment-events` | `eta-group` | Update ETA on shipment changes | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached ETA computations (TTL 300s) | +| Warm (Cosmos DB) | Delivery time history | +| Cold (Blob) | Historical ETA analytics | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/logistics-eta-computation/src uv sync -uv run uvicorn logistics_eta_computation.main:app --reload -python -m pytest ../tests +uv run uvicorn logistics_eta_computation.main:app --reload --port 8015 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/logistics-eta-computation/tests +``` --- diff --git a/apps/logistics-returns-support/README.md b/apps/logistics-returns-support/README.md index 1802cc272..1e8709e13 100644 --- a/apps/logistics-returns-support/README.md +++ b/apps/logistics-returns-support/README.md @@ -1,30 +1,70 @@ # Logistics Returns Support -## Purpose -Supports return-related logistics decisions and operational guidance. - -## Responsibilities -- Assess return flow context and constraints. -- Provide recommendations for return handling steps. -- Surface issues that can delay or block return processing. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Supports return-related logistics decisions by assessing return flow context and constraints. Provides recommendations for return handling steps and surfaces issues that can delay or block return processing. + +## Domain Bounded Context +- **Owner**: Logistics team +- **Bounded Context**: Logistics + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/logistics/returns/context` | Retrieve return logistics context | +| `/logistics/returns/recommend` | Generate return handling recommendation | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `order-events` | `returns-group` | Track orders for return eligibility | +| `return-events` | `returns-group` | React to return lifecycle changes | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached return analysis (TTL 300s) | +| Warm (Cosmos DB) | Return case state | +| Cold (Blob) | Historical returns archives | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/logistics-returns-support/src uv sync -uv run uvicorn logistics_returns_support.main:app --reload -python -m pytest ../tests +uv run uvicorn logistics_returns_support.main:app --reload --port 8016 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/logistics-returns-support/tests +``` --- diff --git a/apps/logistics-route-issue-detection/README.md b/apps/logistics-route-issue-detection/README.md index 56c001275..4c8ddf839 100644 --- a/apps/logistics-route-issue-detection/README.md +++ b/apps/logistics-route-issue-detection/README.md @@ -1,30 +1,69 @@ # Logistics Route Issue Detection -## Purpose -Detects route anomalies and suggests mitigation actions for shipment continuity. - -## Responsibilities -- Monitor route-level disruption indicators. -- Identify likely issue patterns and severity. -- Return mitigation recommendations for operational teams. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Detects route anomalies and suggests mitigation actions for shipment continuity. Monitors route-level disruption indicators, identifies issue patterns and severity, and returns mitigation recommendations. + +## Domain Bounded Context +- **Owner**: Logistics team +- **Bounded Context**: Logistics + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/logistics/route/context` | Retrieve route monitoring context | +| `/logistics/route/issues` | Detect route issues and mitigations | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `order-events` | `route-detect-group` | Monitor orders for route issues | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached route analysis (TTL 300s) | +| Warm (Cosmos DB) | Route disruption history | +| Cold (Blob) | Historical route analytics | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/logistics-route-issue-detection/src uv sync -uv run uvicorn logistics_route_issue_detection.main:app --reload -python -m pytest ../tests +uv run uvicorn logistics_route_issue_detection.main:app --reload --port 8017 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/logistics-route-issue-detection/tests +``` --- diff --git a/apps/product-management-acp-transformation/README.md b/apps/product-management-acp-transformation/README.md index 009015a33..5754f8120 100644 --- a/apps/product-management-acp-transformation/README.md +++ b/apps/product-management-acp-transformation/README.md @@ -1,30 +1,69 @@ # Product Management ACP Transformation -## Purpose -Transforms product payloads into ACP-aligned structures for downstream consumption. - -## Responsibilities -- Map source product fields to ACP-oriented output. -- Detect required-field gaps during transformation. -- Return transformation results and validation context. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Transforms product payloads into ACP (Akeneo Connector Protocol) aligned structures for downstream consumption. Maps source product fields, detects required-field gaps, and returns transformation results with validation context. + +## Domain Bounded Context +- **Owner**: Product Management team +- **Bounded Context**: Product Management + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/acp/transform` | Transform product to ACP format | +| `/acp/context` | Retrieve ACP transformation context | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `product-events` | `acp-transform-group` | Transform on product catalog changes | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached transformation results (TTL 300s) | +| Warm (Cosmos DB) | Transformation state and mappings | +| Cold (Blob) | Transformation history archives | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/product-management-acp-transformation/src uv sync -uv run uvicorn product_management_acp_transformation.main:app --reload -python -m pytest ../tests +uv run uvicorn product_management_acp_transformation.main:app --reload --port 8018 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/product-management-acp-transformation/tests +``` --- diff --git a/apps/product-management-assortment-optimization/README.md b/apps/product-management-assortment-optimization/README.md index 286748449..e4e4cb53b 100644 --- a/apps/product-management-assortment-optimization/README.md +++ b/apps/product-management-assortment-optimization/README.md @@ -1,30 +1,70 @@ # Product Management Assortment Optimization -## Purpose -Optimizes assortment decisions using product performance and relevance signals. - -## Responsibilities -- Rank product candidates for assortment planning. -- Evaluate keep/drop trade-offs for target assortments. -- Return explainable assortment recommendations. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Optimizes assortment decisions using product performance and relevance signals. Ranks product candidates, evaluates keep/drop trade-offs, and returns explainable assortment recommendations. + +## Domain Bounded Context +- **Owner**: Product Management team +- **Bounded Context**: Product Management + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/assortment/context` | Retrieve assortment optimization context | +| `/assortment/recommend` | Generate assortment recommendations | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `order-events` | `assortment-group` | Factor sales velocity into decisions | +| `product-events` | `assortment-group` | React to catalog changes | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached assortment scores (TTL 300s) | +| Warm (Cosmos DB) | Assortment state and performance data | +| Cold (Blob) | Historical assortment analytics | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/product-management-assortment-optimization/src uv sync -uv run uvicorn product_management_assortment_optimization.main:app --reload -python -m pytest ../tests +uv run uvicorn product_management_assortment_optimization.main:app --reload --port 8019 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/product-management-assortment-optimization/tests +``` --- diff --git a/apps/product-management-consistency-validation/README.md b/apps/product-management-consistency-validation/README.md index 1b6b0deb2..4892f1ec2 100644 --- a/apps/product-management-consistency-validation/README.md +++ b/apps/product-management-consistency-validation/README.md @@ -1,30 +1,74 @@ # Product Management Consistency Validation -## Purpose -Validates product consistency and completeness against expected product schemas. - -## Responsibilities -- Assess product records for schema consistency. -- Surface missing or conflicting attribute data. -- Return validation results used by enrichment and review flows. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription: `completeness-jobs` / consumer group `completeness-engine`. +## Purpose -## Run/Test commands +Validates product consistency and completeness against expected product schemas. Assesses records for schema compliance, surfaces missing or conflicting attributes, and returns validation results used by enrichment and review flows. + +## Domain Bounded Context +- **Owner**: Product Management team +- **Bounded Context**: Product Management + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/consistency/validate` | Validate product against schema | +| `/consistency/context` | Retrieve consistency validation context | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `completeness-jobs` (platform) | `completeness-engine` | Validate on completeness job dispatch | + +## Architecture Notes +- Uses platform-jobs Event Hub namespace (separate from domain events) +- Configurable completeness threshold via `COMPLETENESS_THRESHOLD` env var (default: 0.7) + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached validation results (TTL 300s) | +| Warm (Cosmos DB) | Validation state and completeness scores | +| Cold (Blob) | Historical validation archives | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `COMPLETENESS_THRESHOLD` | No | Minimum completeness score (default: 0.7) | +| `PLATFORM_JOBS_EVENTHUB_NAMESPACE` | Yes | Platform jobs Event Hub namespace | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | + +## Local Development ```bash cd apps/product-management-consistency-validation/src uv sync -uv run uvicorn product_management_consistency_validation.main:app --reload -python -m pytest ../tests +uv run uvicorn product_management_consistency_validation.main:app --reload --port 8020 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires the platform-jobs Event Hubs namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/product-management-consistency-validation/tests +``` --- diff --git a/apps/product-management-normalization-classification/README.md b/apps/product-management-normalization-classification/README.md index af97aa732..acbbc66f2 100644 --- a/apps/product-management-normalization-classification/README.md +++ b/apps/product-management-normalization-classification/README.md @@ -1,30 +1,69 @@ -# Product Management Normalization Classification +# Product Management Normalization & Classification -## Purpose -Normalizes and classifies product attributes into canonical representations. - -## Responsibilities -- Normalize product values into expected format and taxonomy. -- Classify product attributes for downstream indexing and logic. -- Return normalization and classification outcomes. +> Last Updated: 2026-04-30 -## Key endpoints or interfaces -- `POST /invoke` for synchronous service requests. -- MCP interfaces under `/mcp/*` for agent-to-agent usage. -- Event Hub subscription for asynchronous processing. +## Purpose -## Run/Test commands +Normalizes and classifies product attributes into canonical representations. Normalizes values into expected format and taxonomy, classifies attributes for downstream indexing, and returns normalization/classification outcomes. + +## Domain Bounded Context +- **Owner**: Product Management team +- **Bounded Context**: Product Management + +## Endpoints + +### REST +| Method | Path | Description | +|--------|------|-------------| +| POST | `/invoke` | Synchronous agent invocation | +| GET | `/health` | Liveness probe | +| GET | `/ready` | Readiness probe | + +### MCP Tools +| Tool | Description | +|------|-------------| +| `/normalization/context` | Retrieve normalization context for a product | +| `/normalization/classify` | Classify and normalize product attributes | + +### Event Subscriptions +| Topic | Consumer Group | Action | +|-------|---------------|--------| +| `product-events` | `normalization-group` | Normalize on product catalog changes | + +## Model Routing +- **SLM (fast)**: GPT-5-nano via `FOUNDRY_AGENT_ID_FAST` +- **LLM (rich)**: GPT-4o via `FOUNDRY_AGENT_ID_RICH` + +## Memory Usage +| Tier | Purpose | +|------|---------|| +| Hot (Redis) | Cached normalization results (TTL 300s) | +| Warm (Cosmos DB) | Taxonomy mappings and classification state | +| Cold (Blob) | Historical normalization archives | + +## Environment Variables +| Variable | Required | Description | +|----------|----------|-------------| +| `PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint | +| `FOUNDRY_AGENT_ID_FAST` | Yes | SLM agent ID | +| `MODEL_DEPLOYMENT_NAME_FAST` | Yes | SLM deployment name | +| `FOUNDRY_AGENT_ID_RICH` | Yes | LLM agent ID | +| `MODEL_DEPLOYMENT_NAME_RICH` | Yes | LLM deployment name | +| `REDIS_URL` | No | Redis connection URL | +| `COSMOS_ACCOUNT_URI` | No | Cosmos DB endpoint | +| `EVENTHUB_NAMESPACE` | Yes | Event Hub namespace | + +## Local Development ```bash cd apps/product-management-normalization-classification/src uv sync -uv run uvicorn product_management_normalization_classification.main:app --reload -python -m pytest ../tests +uv run uvicorn product_management_normalization_classification.main:app --reload --port 8021 ``` -## Configuration notes -- Uses Foundry model settings (`PROJECT_ENDPOINT` or `FOUNDRY_ENDPOINT`, fast/rich model identifiers). -- Supports Redis/Cosmos/Blob memory configuration via shared memory settings. -- Requires Event Hub namespace and consumer configuration for background jobs. +## Test Coverage +```bash +python -m pytest apps/product-management-normalization-classification/tests +``` --- diff --git a/apps/search-enrichment-agent/README.md b/apps/search-enrichment-agent/README.md index ffedbd231..e84023018 100644 --- a/apps/search-enrichment-agent/README.md +++ b/apps/search-enrichment-agent/README.md @@ -1,11 +1,17 @@ # Search Enrichment Agent +> Last Updated: 2026-04-30 + > Full pipeline documentation: [`docs/implementation/truth-layer-agents-guide.md`](../../docs/implementation/truth-layer-agents-guide.md) ## Purpose Generates search-optimized content (keywords, facets, marketing copy, sustainability signals) for products and pushes them to Azure AI Search. Acts as the **discovery amplification stage** of the Product Truth Layer pipeline. +## Domain Bounded Context +- **Owner**: Search team +- **Bounded Context**: Search + ## Why This Agent Exists Raw product attributes are insufficient for high-quality search. Customers search using natural language, synonyms, and intent-based queries. This agent transforms structured product data into discovery-optimized content that powers semantic and keyword search. diff --git a/apps/truth-enrichment/README.md b/apps/truth-enrichment/README.md index 91a5d0b03..51bebd3f4 100644 --- a/apps/truth-enrichment/README.md +++ b/apps/truth-enrichment/README.md @@ -1,11 +1,17 @@ # Truth Enrichment +> Last Updated: 2026-04-30 + > Full pipeline documentation: [`docs/implementation/truth-layer-agents-guide.md`](../../docs/implementation/truth-layer-agents-guide.md) ## Purpose Detects missing product attributes by comparing ingested products against category-specific schemas, then proposes AI-generated values using text reasoning and vision analysis. Acts as the **second stage** of the Product Truth Layer pipeline. +## Domain Bounded Context +- **Owner**: Truth Layer team +- **Bounded Context**: Truth Layer + ## Why This Agent Exists Products arrive from PIM with incomplete data — missing colors, materials, dimensions, care instructions. Manual data entry is expensive and slow. This agent automates attribute gap-fill using AI while maintaining a human review checkpoint for quality assurance. diff --git a/apps/truth-export/README.md b/apps/truth-export/README.md index ddc4462c2..2bcce45ef 100644 --- a/apps/truth-export/README.md +++ b/apps/truth-export/README.md @@ -1,11 +1,17 @@ # Truth Export +> Last Updated: 2026-04-30 + > Full pipeline documentation: [`docs/implementation/truth-layer-agents-guide.md`](../../docs/implementation/truth-layer-agents-guide.md) ## Purpose Transforms approved product truth into protocol-specific formats (UCP/ACP) and manages PIM writeback. Acts as the **export stage** of the Product Truth Layer pipeline. +## Domain Bounded Context +- **Owner**: Truth Layer team +- **Bounded Context**: Truth Layer + ## Why This Agent Exists Once attributes are validated by HITL, they must flow back to the systems of record. Different downstream consumers require different formats (UCP for universal distribution, ACP for agent interoperability). This agent ensures **approved truth reaches source PIM systems** in their expected format. diff --git a/apps/truth-hitl/README.md b/apps/truth-hitl/README.md index 022743cc2..96ac87067 100644 --- a/apps/truth-hitl/README.md +++ b/apps/truth-hitl/README.md @@ -1,11 +1,17 @@ # Truth HITL +> Last Updated: 2026-04-30 + > Full pipeline documentation: [`docs/implementation/truth-layer-agents-guide.md`](../../docs/implementation/truth-layer-agents-guide.md) ## Purpose Manages the human-in-the-loop review queue for AI-proposed product attributes. Acts as the **quality gate** between AI-generated proposals and canonical approved truth. +## Domain Bounded Context +- **Owner**: Truth Layer team +- **Bounded Context**: Truth Layer + ## Why This Agent Exists AI-generated product attributes cannot be trusted blindly — incorrect values damage catalog quality and customer trust. This agent ensures **human validation** before any AI-proposed value becomes truth, providing full audit trails and decision governance. diff --git a/apps/truth-ingestion/README.md b/apps/truth-ingestion/README.md index fca565c88..93fe42caf 100644 --- a/apps/truth-ingestion/README.md +++ b/apps/truth-ingestion/README.md @@ -1,11 +1,17 @@ # Truth Ingestion +> Last Updated: 2026-04-30 + > Full pipeline documentation: [`docs/implementation/truth-layer-agents-guide.md`](../../docs/implementation/truth-layer-agents-guide.md) ## Purpose Ingests raw product data from PIM (Product Information Management) and DAM (Digital Asset Management) sources into the canonical truth store. Acts as the **first stage** of the Product Truth Layer pipeline. +## Domain Bounded Context +- **Owner**: Truth Layer team +- **Bounded Context**: Truth Layer + ## Why This Agent Exists Retail platforms integrate with dozens of PIM/DAM vendors, each with proprietary schemas. This agent creates a single normalized data format (`ProductStyle`/`ProductVariant`) that all downstream agents rely on without coupling to vendor-specific APIs. diff --git a/apps/ui/README.md b/apps/ui/README.md index 1db96490c..481ed848f 100644 --- a/apps/ui/README.md +++ b/apps/ui/README.md @@ -1,39 +1,251 @@ -# UI +# Holiday Peak Hub — UI -## Purpose -Provides the Next.js frontend for Holiday Peak Hub operations and workflows. +> **Last Updated**: 2026-04-30 -## Responsibilities -- Render admin and operations interfaces for retail workflows. -- Call backend APIs for transactional and intelligence scenarios. -- Provide a single web entry point for platform users. +Next.js 16 App Router frontend for the Holiday Peak Hub intelligent retail platform. Deployed on Azure Static Web Apps with TypeScript strict mode, Tailwind CSS, and React Query. -## Key endpoints or interfaces -- Next.js app interface served through the standard web root. -- API integration targets are configured through frontend environment variables. +--- + +## Architecture Overview + +```mermaid +%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#FFB3BA','primaryTextColor':'#000','primaryBorderColor':'#FF8B94','lineColor':'#BAE1FF','secondaryColor':'#BAE1FF','tertiaryColor':'#FFFFFF'}}}%% +graph TB + subgraph Browser + A[Next.js App Router] --> B[React Query Cache] + A --> C[AuthContext / ThemeContext] + A --> D[AgentRobotOverlay System] + end + subgraph Proxy Layer + E["/api/*" CRUD Proxy] + F["/agent-api/*" Agent Proxy] + end + subgraph Backend + G[CRUD Service via APIM] + H[Agent Services via APIM] + end + A --> E --> G + A --> F --> H +``` + +## Tech Stack + +| Layer | Technology | Version | +|-------|-----------|---------| +| Framework | Next.js (App Router) | 16.x | +| Language | TypeScript (strict) | 5.x | +| UI Library | React | 19.x | +| Styling | Tailwind CSS + custom design tokens | 4.x | +| Server State | @tanstack/react-query | 5.x | +| Client State | React Context + useReducer | — | +| Auth | @azure/msal-browser + @azure/msal-react | 5.x | +| Payments | @stripe/react-stripe-js | 4.x | +| Charts | Recharts | 2.x | +| Forms | react-hook-form | 7.x | +| Testing | Jest + React Testing Library + Playwright | — | +| Package Manager | Yarn | — | +| Deployment | Azure Static Web Apps (standalone output) | — | + +## Project Structure + +``` +apps/ui/ +├── app/ # Next.js App Router pages and route handlers +│ ├── layout.tsx # Root layout (Providers wrapper) +│ ├── providers.tsx # AuthProvider → QueryProvider → ThemeProvider → PageSessionProvider +│ ├── page.tsx # Homepage — executive demo narrative +│ ├── admin/ # Admin control plane routes +│ ├── agent-api/ # Agent proxy route handlers +│ ├── api/ # CRUD proxy route handlers +│ ├── cart/ # Shopping cart +│ ├── categories/ # Category catalog +│ ├── category/ # Single category browse +│ ├── checkout/ # Checkout flow +│ ├── dashboard/ # Customer dashboard +│ ├── demo/ # Demo utilities (color system) +│ ├── order/ # Single order detail +│ ├── orders/ # Order history +│ ├── product/ # Product detail +│ ├── profile/ # User profile +│ ├── scenarios/ # Agent scenario playground +│ ├── search/ # Semantic search +│ ├── shop/ # Catalog landing +│ ├── staff/ # Staff operations (sales, review, requests, logistics) +│ └── _shared/ # Shared route utilities +├── components/ # Atomic Design component library +│ ├── atoms/ # Button, Badge, Input, Skeleton, Spinner, ThemeToggle... +│ ├── molecules/ # Card, ProductCard, SearchInput, Modal, Tabs, Timeline... +│ ├── organisms/ # AgentRobotOverlay, Navigation, HeroSlider, ProductGrid, ChatWidget... +│ ├── templates/ # MainLayout, CommerceAgentLayout, CheckoutLayout, ShopLayout... +│ ├── demo/ # ExecutiveDemoPage, AgentProfileDrawer, AgentFrieze +│ ├── enrichment/ # AttributeDiffView, SearchResultCard, CsvUploadPanel... +│ ├── truth/ # ReviewQueueTable, ProposalCard, ConfidenceBadge... +│ └── admin/ # EvaluationTrendChart, TraceWaterfall, PipelineFlowDiagram... +├── contexts/ # AuthContext, ThemeContext +├── lib/ # Shared logic +│ ├── api/ # apiClient (CRUD), agentClient (Agent), endpoints +│ ├── agents/ # Agent profile registry (profiles.ts) +│ ├── hooks/ # React Query hooks (useProducts, useCart, useSemanticSearch...) +│ ├── services/ # agentStreamingService (SSE) +│ ├── providers/ # QueryProvider, PageSessionProvider +│ ├── types/ # TypeScript API type definitions +│ └── utils/ # Utility functions (formatters, mappers) +├── layouts/ # Legacy layout CSS +├── css/ # Additional CSS modules +├── public/ # Static assets +├── slices/ # Redux slices (legacy, migrating to React Query) +├── tests/ +│ ├── unit/ # Jest + RTL unit tests +│ └── e2e/ # Playwright E2E specs +├── next.config.js # Next.js configuration +├── tailwind.config.ts # Tailwind design tokens +├── tsconfig.json # TypeScript strict config +├── jest.config.js # Jest with coverage thresholds +├── playwright.config.ts # Playwright E2E config +└── staticwebapp.config.json # Azure SWA routing +``` + +## Route Map + +| Route | Responsibility | Agent Integration | +|-------|---------------|-------------------| +| `/` | Homepage — executive demo scroll narrative with agent orchestra | Full (RobotScatterIntro, AgentFrieze) | +| `/categories` | Category atlas with live catalog data | — | +| `/category?slug=...` | Category browse with filter rail | CommerceAgentLayout | +| `/product?id=...` | Product detail with enrichment tabs | CommerceAgentLayout (product-detail-enrichment) | +| `/search` | Semantic search via `useSemanticSearch` + `useStreamingSearch` | CommerceAgentLayout (catalog-search) | +| `/cart` | Shopping cart (CRUD-backed) | CommerceAgentLayout (cart-intelligence) | +| `/checkout` | Stripe-integrated checkout flow | CheckoutLayout | +| `/orders` | Order history list | CommerceAgentLayout | +| `/order/[id]` | Order lifecycle detail with logistics robots | CommerceAgentLayout (route-issue-detection + returns) | +| `/shop` | Catalog landing | ShopLayout | +| `/deals` | Deals search shortcut | — | +| `/dashboard` | Customer dashboard (orders, recommendations) | — | +| `/profile` | Account settings | — | +| `/scenarios/[id]` | Agent scenario playground | Full invocation UI | +| `/staff/sales` | Sales performance cockpit | — | +| `/staff/review` | Product enrichment review queue | Truth components | +| `/staff/requests` | Support tickets and returns | — | +| `/staff/logistics` | Shipment monitoring | — | +| `/admin` | Admin control-plane home | — | +| `/admin/agent-activity` | Agent observability cockpit | TraceWaterfall, EvaluationTrendChart | +| `/admin/enrichment-monitor` | Enrichment pipeline board | PipelineFlowDiagram | +| `/admin/truth-analytics` | Truth layer analytics | — | +| `/admin/config` | Platform configuration | — | +| `/admin/schemas` | Schema builder | — | +| `/agents/product-enrichment-chat` | Direct agent chat UI | Full | + +## Agent Robot Overlay System + +The `AgentRobotOverlay` component renders animated agent robot personas that appear contextually during user interactions: + +```mermaid +%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#FFB3BA','primaryTextColor':'#000','primaryBorderColor':'#FF8B94','lineColor':'#BAE1FF','secondaryColor':'#BAE1FF','tertiaryColor':'#FFFFFF'}}}%% +graph LR + A[AgentRobotOverlay] --> B[AgentRobot] + A --> C[Position: bottom-right / bottom-left / inline] + A --> D[States: idle / thinking / talking / using-tool / entering / waving] + E[CommerceAgentLayout] --> A + E --> F[Primary Robot - lead agent for page] + E --> G[SideCast Robots - collaborating agents] + E --> H[Telemetry Chip - tier/latency/cost/tokens] +``` + +- **`AgentRobotOverlay`** — Positioned wrapper with entrance/exit animations. Configured by `agentSlug`, `state`, `position`, `size`, and `facing`. +- **`CommerceAgentLayout`** — Template that standardizes primary + side-cast robots and compact telemetry chips across commerce routes (cart, search, category, product, checkout, orders). +- **`AgentProfileDrawer`** — Slide-out panel showing agent input/output schemas, sample invocations with SSE streaming, and an in-place trace explorer backed by admin monitor APIs. +- **`ExecutiveDemoPage`** — Scroll-driven executive demo that orchestrates 26 agents across Customer 360, commerce, inventory, logistics, and observability sections. + +## API Client Architecture (ADR-016) + +Two Axios clients route requests through same-origin Next.js proxy routes to avoid CORS: + +| Client | File | Base Route | Upstream | +|--------|------|-----------|----------| +| `apiClient` | `lib/api/client.ts` | `/api/*` | CRUD Service (via APIM) | +| `agentApiClient` | `lib/api/agentClient.ts` | `/agent-api/*` | Agent Services (via APIM) | + +**Base URL resolution** (server-side fallback chain): +- CRUD: `NEXT_PUBLIC_CRUD_API_URL` → `NEXT_PUBLIC_API_URL` → `CRUD_API_URL` +- Agent: `NEXT_PUBLIC_AGENT_API_URL` → `AGENT_API_URL` + +**SSE streaming** for agent invocations uses `/invoke/stream` endpoints via `agentStreamingService`. + +**Page session**: `usePageSession` hook injects `x-holiday-peak-session-id` into agent requests for Foundry conversation thread reuse. + +## Tailwind Design Tokens + +Custom color palette defined in `tailwind.config.ts`: + +| Token | Scale | Usage | +|-------|-------|-------| +| `ocean-*` | 50–900 | Primary brand (blues) | +| `lime-*` | 50–900 | Success/secondary (greens) | +| `cyan-*` | 50–900 | Accent (teals) | +| `hp-*` | CSS variables | Semantic tokens (bg, surface, text, border, primary, accent, focus) | + +Dark mode: class-based (`darkMode: 'class'`), toggled via `ThemeContext` + `ThemeToggle` atom. + +Font: Inter (sans-serif). + +## State Management + +| Concern | Mechanism | +|---------|-----------| +| Server state (products, orders, cart) | `@tanstack/react-query` via hooks in `lib/hooks/` | +| Auth state | `AuthContext` (MSAL + dev mock mode) | +| Theme | `ThemeContext` (light/dark) | +| Page session | `PageSessionProvider` (Foundry thread ID per page) | +| Legacy slices | Redux Toolkit (`slices/`) — migrating to React Query | + +## Run / Test Commands -## Run/Test commands ```bash yarn --cwd apps/ui install -yarn --cwd apps/ui dev -yarn --cwd apps/ui test -yarn --cwd apps/ui test:coverage -yarn --cwd apps/ui test:e2e -yarn --cwd apps/ui lint -yarn --cwd apps/ui type-check +yarn --cwd apps/ui dev # Local dev server (port 3000) +yarn --cwd apps/ui build # Production build (standalone output) +yarn --cwd apps/ui start # Start production server +yarn --cwd apps/ui test # Jest unit tests +yarn --cwd apps/ui test:coverage # Jest with coverage report +yarn --cwd apps/ui test:e2e # Playwright E2E tests +yarn --cwd apps/ui lint # ESLint (zero warnings enforced) +yarn --cwd apps/ui type-check # tsc --noEmit strict check ``` -## Coverage and quality gates -- Jest enforces global coverage thresholds (`branches/functions/lines/statements >= 60%`) in `apps/ui/jest.config.js`. -- Baseline critical-flow E2E coverage runs through Playwright (`apps/ui/tests/e2e/critical-flows.spec.ts`). -- Executive demo and operator regression coverage now also includes `apps/ui/tests/e2e/demo-narrative.spec.ts`, `apps/ui/tests/e2e/dark-mode-regression.spec.ts`, and `apps/ui/tests/e2e/cockpit-readiness.spec.ts`. -- Focused unit coverage also validates telemetry persistence for enrichment-backed product loads and graph-summary enrichment calls. - -## Configuration notes -- Uses frontend environment variables for backend/API URLs and auth integration. -- Build and runtime behavior are controlled by `apps/ui/package.json` scripts. -- Uses Next.js and TypeScript toolchain configured in the UI app directory. -- Commerce drill-down routes now share `CommerceAgentLayout`, which standardizes the primary-stage robot, side-cast robot, and compact telemetry chip across cart, search, category, product, checkout, orders, order detail, and hint pages. -- Agent profile drawers now expose input/output schemas, curated sample invocations, SSE-backed sample streaming, and an in-place trace explorer backed by the existing admin monitor APIs. -- The compact telemetry chip now hydrates from persisted `_telemetry` emitted by sample streaming, search, product enrichment, and graph-summary invoke paths instead of placeholder state. -- Order detail now keeps `logistics-route-issue-detection` visible as the default side cast until a return flow is actively opened, at which point the duet swaps to returns plus support assistance. +## Coverage and Quality Gates + +- Jest enforces global coverage thresholds (`branches/functions/lines/statements >= 60%`) in `jest.config.js`. +- Playwright E2E specs: + - `tests/e2e/critical-flows.spec.ts` — Baseline critical-flow coverage. + - `tests/e2e/demo-narrative.spec.ts` — Executive demo scroll narrative. + - `tests/e2e/dark-mode-regression.spec.ts` — Dark mode visual regression. + - `tests/e2e/cockpit-readiness.spec.ts` — Admin cockpit readiness. +- Focused unit coverage validates telemetry persistence for enrichment-backed product loads and graph-summary enrichment calls. + +## Accessibility (WCAG 2.2 AA) + +- Skip link to `#main-content` on every page. +- Semantic landmarks (`
`, `