@rlynjb/aptkit-core 0.1.0

package/node_modules/@aptkit/agent-recommendation/fixtures/electronics-spike.json

@@ -0,0 +1,84 @@
+{
+  "id": "electronics-spike-w2",
+  "description": "Fixture derived from Blooming Insights recommendation regression case 07-recommendation-electronics.",
+  "workspace": {
+    "projectId": "olist",
+    "projectName": "Olist Brazilian ecommerce fixture",
+    "events": [
+      { "name": "order", "properties": ["state", "category", "purchase_ts", "price_brl"], "eventCount": 0 },
+      { "name": "payment", "properties": ["type", "installments", "value_brl"], "eventCount": 0 }
+    ],
+    "customerProperties": ["state", "city"],
+    "catalogs": [{ "id": "products", "name": "Products" }],
+    "totalCustomers": 0,
+    "totalEvents": 0,
+    "oldestTimestamp": null,
+    "dataHorizon": { "from": "2025-12-01", "to": "2026-06-01", "durationDays": 182 }
+  },
+  "anomaly": {
+    "metric": "order_count",
+    "scope": ["category:electronics"],
+    "change": {
+      "value": 150,
+      "direction": "up",
+      "baseline": "week 2 (2025-12-08 to 2025-12-15) vs 12-week baseline"
+    },
+    "severity": "positive",
+    "evidence": [],
+    "impact": "Electronics order count spiked about 2.5x across multiple states."
+  },
+  "diagnosis": {
+    "conclusion": "Electronics order count spiked about 2.5x in week 2 versus baseline. The spike is broad across states, revenue scaled with order count, and AOV stayed stable, so this appears to be a real demand surge rather than a single large-buyer artifact.",
+    "evidence": [
+      "get_anomaly_context(metric=order_count, dimension=category, segment=electronics) returned pct_change=+1.50 for week 2.",
+      "SP, RJ, MG, RS, and PR were all up 100-200% in week 2.",
+      "Revenue scaled with order count, with AOV roughly flat.",
+      "No other category moved with electronics that week."
+    ],
+    "hypothesesConsidered": [
+      {
+        "hypothesis": "Single large buyer distorted the metric",
+        "supported": false,
+        "reasoning": "The spike was distributed across states and many customers."
+      },
+      {
+        "hypothesis": "Electronics-specific promotional or seasonal pull",
+        "supported": true,
+        "reasoning": "The category moved broadly while other categories did not."
+      }
+    ],
+    "affectedCustomers": {
+      "count": 8800,
+      "segmentDescription": "Electronics buyers across BR states in week 2"
+    },
+    "confidence": "medium"
+  },
+  "tools": [
+    { "name": "list_segmentations", "description": "List existing segments", "inputSchema": { "type": "object" }, "result": { "data": [{ "name": "electronics buyers" }, { "name": "recent accessory buyers" }] } },
+    { "name": "list_email_campaigns", "description": "List email campaigns", "inputSchema": { "type": "object" }, "result": { "data": [{ "name": "holiday electronics promo" }] } },
+    { "name": "list_recommendations", "description": "List recommendation models", "inputSchema": { "type": "object" }, "result": { "data": [{ "name": "accessory cross-sell" }] } }
+  ],
+  "modelResponses": [
+    {
+      "content": [
+        { "type": "tool_use", "id": "tool-1", "name": "list_segmentations", "input": { "project_id": "olist" } },
+        { "type": "tool_use", "id": "tool-2", "name": "list_recommendations", "input": { "project_id": "olist" } }
+      ],
+      "usage": { "inputTokens": 910, "outputTokens": 80 },
+      "model": "fixture-model"
+    },
+    {
+      "content": [
+        {
+          "type": "text",
+          "text": "```json\n[{\"title\":\"Cross-sell accessories to week-2 electronics buyers\",\"rationale\":\"The diagnosis shows a real electronics demand surge with stable AOV. A follow-on campaign can turn one-time electronics purchases into higher LTV by promoting complementary accessories while purchase recency is high.\",\"bloomreachFeature\":\"campaign\",\"steps\":[\"Build a segment of customers who bought electronics in week 2.\",\"Send a 3-week accessory campaign featuring cables, cases, warranties, and setup bundles.\",\"Exclude customers who already bought accessories after the electronics order.\"],\"estimatedImpact\":{\"range\":\"+$70k - $140k incremental revenue over 21 days\",\"rangeUsd\":{\"low\":70000,\"high\":140000},\"assumption\":\"Assumes 5-10% accessory attach rate on 8800 electronics buyers at about $160 accessory order value.\"},\"effort\":\"medium\",\"timeToSetUpMinutes\":120,\"readResultInDays\":21,\"prerequisites\":[{\"label\":\"electronics buyer segment available\",\"satisfied\":true},{\"label\":\"accessory recommendation model available\",\"satisfied\":true}],\"successMetric\":\"Accessory attach rate rises from about 3% baseline to 5-10% over 21 days.\",\"confidence\":\"medium\"},{\"title\":\"Identify top electronics SKUs behind the spike\",\"rationale\":\"The spike looks real, but the reusable playbook depends on whether a few SKUs or the whole category drove it. A segment analysis gates whether to rerun a promotion or build a seasonal calendar trigger.\",\"bloomreachFeature\":\"segment\",\"steps\":[\"Create a week-2 electronics order segment.\",\"Rank SKUs by order count and compare their share to baseline.\",\"Classify the spike as concentrated promotion or broad seasonal pull.\"],\"estimatedImpact\":{\"range\":\"Diagnostic: gates repeat-promo investment\",\"assumption\":\"No direct lift; prevents scaling the wrong electronics playbook.\"},\"effort\":\"low\",\"timeToSetUpMinutes\":30,\"readResultInDays\":2,\"prerequisites\":[{\"label\":\"SKU-level order data accessible\",\"satisfied\":true}],\"successMetric\":\"Top-10 SKU share classified as concentrated above 50% or broad below 30%.\",\"confidence\":\"high\"}]\n```"
+        }
+      ],
+      "usage": { "inputTokens": 1350, "outputTokens": 610 },
+      "model": "fixture-model"
+    }
+  ],
+  "eval": {
+    "requiredFields": ["0.title", "0.rationale", "0.bloomreachFeature", "0.steps", "0.estimatedImpact", "0.confidence"]
+  }
+}

package/node_modules/@aptkit/agent-recommendation/fixtures/promoted/voucher-dropoff-w10-on-openai-promoted-2026-06-18-16-53-02.json

@@ -0,0 +1,166 @@
+{
+  "id": "voucher-dropoff-w10-on-openai-promoted",
+  "description": "Promoted deterministic fixture from openai replay artifact. Source fixture: voucher-dropoff-w10-on. Replay created at: 2026-06-18T16:53:02.698Z.",
+  "workspace": {
+    "projectId": "olist",
+    "projectName": "Olist Brazilian ecommerce fixture",
+    "events": [
+      {
+        "name": "order",
+        "properties": [
+          "state",
+          "category",
+          "purchase_ts",
+          "price_brl"
+        ],
+        "eventCount": 0
+      },
+      {
+        "name": "payment",
+        "properties": [
+          "type",
+          "installments",
+          "value_brl"
+        ],
+        "eventCount": 0
+      }
+    ],
+    "customerProperties": [
+      "state",
+      "city"
+    ],
+    "catalogs": [],
+    "totalCustomers": 0,
+    "totalEvents": 0,
+    "oldestTimestamp": null,
+    "dataHorizon": {
+      "from": "2025-12-01",
+      "to": "2026-06-01",
+      "durationDays": 182
+    }
+  },
+  "anomaly": {
+    "metric": "payment_value",
+    "scope": [
+      "payment_type:voucher"
+    ],
+    "change": {
+      "value": 95,
+      "direction": "down",
+      "baseline": "weeks 10-26 vs weeks 1-9 baseline"
+    },
+    "severity": "critical",
+    "evidence": [],
+    "impact": "Voucher payment value collapsed to about 5% of baseline and stayed depressed."
+  },
+  "diagnosis": {
+    "conclusion": "Voucher payment volume collapsed to roughly 5% of baseline starting week 10 and remained depressed through the end of the data horizon. Credit card and boleto did not absorb the lost volume, and order count fell, so this is likely a program-level voucher change rather than clean substitution.",
+    "evidence": [
+      "get_anomaly_context(metric=payment_value, dimension=payment_type, segment=voucher) returned pct_change=-0.95 for weeks 10-26.",
+      "Credit_card and boleto did not rise enough to absorb the lost voucher volume.",
+      "Total order_count was about 8% below baseline after the voucher cliff.",
+      "The drop was uniform across SP, RJ, and MG."
+    ],
+    "hypothesesConsidered": [
+      {
+        "hypothesis": "Voucher volume substituted to credit card or boleto",
+        "supported": false,
+        "reasoning": "Other payment types did not rise and total order count fell."
+      },
+      {
+        "hypothesis": "Program-level voucher change",
+        "supported": true,
+        "reasoning": "The cliff-shaped onset and sustained cross-state impact fit suspension, expiry, or restriction."
+      }
+    ],
+    "affectedCustomers": {
+      "count": 12500,
+      "segmentDescription": "Customers who previously used voucher payment in weeks 1-9"
+    },
+    "confidence": "medium"
+  },
+  "tools": [
+    {
+      "name": "list_voucher_pools",
+      "description": "List voucher pools",
+      "inputSchema": {
+        "type": "object"
+      },
+      "result": {
+        "data": []
+      }
+    },
+    {
+      "name": "list_email_campaigns",
+      "description": "List email campaigns",
+      "inputSchema": {
+        "type": "object"
+      },
+      "result": {
+        "data": [
+          {
+            "name": "inactive customer broadcast"
+          }
+        ]
+      }
+    },
+    {
+      "name": "get_frequency_policies",
+      "description": "List frequency policies",
+      "inputSchema": {
+        "type": "object"
+      },
+      "result": {
+        "data": [
+          {
+            "name": "one marketing message per week"
+          }
+        ]
+      }
+    }
+  ],
+  "modelResponses": [
+    {
+      "content": [
+        {
+          "type": "text",
+          "text": "```json\n[\n  {\n    \"title\": \"Reinstate or Launch New Voucher Incentive for Lapsed Voucher Users\",\n    \"rationale\": \"Since voucher usage has collapsed and was not replaced by other payment types, reinstating a voucher offer can help recover lost order volume from affected customers who previously relied on vouchers. The order count decline suggests many of these users have likely lapsed, representing material lost revenue.\",\n    \"bloomreachFeature\": \"voucher\",\n    \"steps\": [\n      \"Create a new voucher pool or campaign targeting customers who used vouchers in weeks 1-9 but stopped purchasing after week 10.\",\n      \"Design the voucher to be attractive enough to re-engage this audience (e.g., similar or better than previous offers, possibly with a limited-time urgency).\",\n      \"Communicate the voucher via email or SMS to maximize reach and conversion.\"\n    ],\n    \"estimatedImpact\": {\n      \"range\": \"Moderate to High (USD 10,000 - 40,000 regained revenue)\",\n      \"rangeUsd\": {\n        \"low\": 10000,\n        \"high\": 40000\n      },\n      \"assumption\": \"Assumes recapturing 20 - 50% of the estimated $45,000+ in lost voucher-order GMV (baseline $1,500/week x 16 weeks x 12500 customers)\"\n    },\n    \"confidence\": \"high\",\n    \"effort\": \"medium\",\n    \"timeToSetUpMinutes\": 60,\n    \"readResultInDays\": 14,\n    \"prerequisites\": [\n      {\n        \"label\": \"Voucher engine configured\",\n        \"satisfied\": true\n      },\n      {\n        \"label\": \"Segment of lapsed voucher users available\",\n        \"satisfied\": true\n      }\n    ],\n    \"successMetric\": \"Number of recovered orders from targeted lapsed voucher users; baseline: 0/wk, target: +150/wk\"\n  },\n  {\n    \"title\": \"Segment Analysis: Identify and Profile Lapsed Voucher Customers\",\n    \"rationale\": \"A well-defined segment of customers who stopped ordering when voucher incentives ended is critical for targeted recovery and ongoing program design. Understanding their value and response patterns informs further interventions.\",\n    \"bloomreachFeature\": \"segment\",\n    \"steps\": [\n      \"Define a segment encompassing all customers who used voucher payments in weeks 1-9 but placed zero orders in weeks 10-26.\",\n      \"Analyze this segment for order value, category mix, and location to prioritize outreach.\",\n      \"Feed this segment into marketing or win-back initiatives.\"\n    ],\n    \"estimatedImpact\": \"Medium; enables more effective targeting for campaigns and reduces wasted marketing spend.\",\n    \"confidence\": \"high\",\n    \"effort\": \"low\",\n    \"timeToSetUpMinutes\": 30,\n    \"readResultInDays\": 3,\n    \"prerequisites\": [\n      {\n        \"label\": \"Customer order-by-payment-type data available\",\n        \"satisfied\": true\n      }\n    ],\n    \"successMetric\": \"Segment accuracy and percentage overlap with lost voucher revenue group; baseline: n/a, target: >85%\"\n  },\n  {\n    \"title\": \"A/B Test: Voucher Value or Friction Experiment\",\n    \"rationale\": \"Run an experiment restoring voucher value or relaxing criteria (e.g., minimum spend, eligible SKUs) for a sample of lapsed users to validate whether incentive structure - not external factors - caused the drop.\",\n    \"bloomreachFeature\": \"experiment\",\n    \"steps\": [\n      \"Randomly assign lapsed voucher users to test and control groups.\",\n      \"Offer the test group an updated voucher similar to the previous baseline program.\",\n      \"Monitor recovery of orders and compare to control to assess direct causality and incremental lift.\"\n    ],\n    \"estimatedImpact\": \"Medium to high if program-level changes caused the drop; validates full-scale reinstatement potential.\",\n    \"confidence\": \"medium\",\n    \"effort\": \"medium\",\n    \"timeToSetUpMinutes\": 90,\n    \"readResultInDays\": 21,\n    \"prerequisites\": [\n      {\n        \"label\": \"Ability to randomize voucher distribution\",\n        \"satisfied\": true\n      },\n      {\n        \"label\": \"Segment of lapsed voucher users identified\",\n        \"satisfied\": false\n      }\n    ],\n    \"successMetric\": \"Test group uplift over control in new orders; baseline: 0, target: +10% or more\"\n  }\n]\n```"
+        }
+      ],
+      "usage": {
+        "inputTokens": 1052,
+        "outputTokens": 915,
+        "estimated": true
+      },
+      "model": "promoted-openai-replay"
+    }
+  ],
+  "eval": {
+    "requiredFields": [
+      "0.title",
+      "0.rationale",
+      "0.bloomreachFeature",
+      "0.steps",
+      "0.estimatedImpact",
+      "0.confidence"
+    ]
+  },
+  "expectations": {
+    "requiredFeatures": [
+      "voucher"
+    ],
+    "requiredText": [
+      "lapsed voucher users",
+      "experiment"
+    ]
+  },
+  "promotion": {
+    "sourceArtifact": "artifacts/replays/2026-06-18T16-53-02-698Z-voucher-dropoff-w10-on-openai.json",
+    "sourceProvider": {
+      "id": "openai",
+      "model": "gpt-4.1"
+    },
+    "promotedAt": "2026-06-18T17:01:37.868Z",
+    "note": "This fixture captures the final replay answer deterministically; it does not reconstruct the live provider tool loop."
+  }
+}

package/node_modules/@aptkit/agent-recommendation/fixtures/promoted/voucher-dropoff-w10-on-openai-promoted-2026-06-18-17-20-55.json

@@ -0,0 +1,157 @@
+{
+  "id": "voucher-dropoff-w10-on-openai-promoted",
+  "description": "Promoted deterministic fixture from openai replay artifact. Source fixture: voucher-dropoff-w10-on. Replay created at: 2026-06-18T17:20:55.422Z.",
+  "workspace": {
+    "projectId": "olist",
+    "projectName": "Olist Brazilian ecommerce fixture",
+    "events": [
+      {
+        "name": "order",
+        "properties": [
+          "state",
+          "category",
+          "purchase_ts",
+          "price_brl"
+        ],
+        "eventCount": 0
+      },
+      {
+        "name": "payment",
+        "properties": [
+          "type",
+          "installments",
+          "value_brl"
+        ],
+        "eventCount": 0
+      }
+    ],
+    "customerProperties": [
+      "state",
+      "city"
+    ],
+    "catalogs": [],
+    "totalCustomers": 0,
+    "totalEvents": 0,
+    "oldestTimestamp": null,
+    "dataHorizon": {
+      "from": "2025-12-01",
+      "to": "2026-06-01",
+      "durationDays": 182
+    }
+  },
+  "anomaly": {
+    "metric": "payment_value",
+    "scope": [
+      "payment_type:voucher"
+    ],
+    "change": {
+      "value": 95,
+      "direction": "down",
+      "baseline": "weeks 10-26 vs weeks 1-9 baseline"
+    },
+    "severity": "critical",
+    "evidence": [],
+    "impact": "Voucher payment value collapsed to about 5% of baseline and stayed depressed."
+  },
+  "diagnosis": {
+    "conclusion": "Voucher payment volume collapsed to roughly 5% of baseline starting week 10 and remained depressed through the end of the data horizon. Credit card and boleto did not absorb the lost volume, and order count fell, so this is likely a program-level voucher change rather than clean substitution.",
+    "evidence": [
+      "get_anomaly_context(metric=payment_value, dimension=payment_type, segment=voucher) returned pct_change=-0.95 for weeks 10-26.",
+      "Credit_card and boleto did not rise enough to absorb the lost voucher volume.",
+      "Total order_count was about 8% below baseline after the voucher cliff.",
+      "The drop was uniform across SP, RJ, and MG."
+    ],
+    "hypothesesConsidered": [
+      {
+        "hypothesis": "Voucher volume substituted to credit card or boleto",
+        "supported": false,
+        "reasoning": "Other payment types did not rise and total order count fell."
+      },
+      {
+        "hypothesis": "Program-level voucher change",
+        "supported": true,
+        "reasoning": "The cliff-shaped onset and sustained cross-state impact fit suspension, expiry, or restriction."
+      }
+    ],
+    "affectedCustomers": {
+      "count": 12500,
+      "segmentDescription": "Customers who previously used voucher payment in weeks 1-9"
+    },
+    "confidence": "medium"
+  },
+  "tools": [
+    {
+      "name": "list_voucher_pools",
+      "description": "List voucher pools",
+      "inputSchema": {
+        "type": "object"
+      },
+      "result": {
+        "data": []
+      }
+    },
+    {
+      "name": "list_email_campaigns",
+      "description": "List email campaigns",
+      "inputSchema": {
+        "type": "object"
+      },
+      "result": {
+        "data": [
+          {
+            "name": "inactive customer broadcast"
+          }
+        ]
+      }
+    },
+    {
+      "name": "get_frequency_policies",
+      "description": "List frequency policies",
+      "inputSchema": {
+        "type": "object"
+      },
+      "result": {
+        "data": [
+          {
+            "name": "one marketing message per week"
+          }
+        ]
+      }
+    }
+  ],
+  "modelResponses": [
+    {
+      "content": [
+        {
+          "type": "text",
+          "text": "```json\n[\n  {\n    \"title\": \"Reactivate Voucher Incentives for Lost Voucher Users\",\n    \"rationale\": \"A sudden and sustained drop in voucher usage affected ~12,500 customers and led to an 8% overall order decline. To recover lost conversion, an automated scenario targeting voucher users pre-week 10 should reintroduce vouchers or explain changes.\",\n    \"bloomreachFeature\": \"scenario\",\n    \"steps\": [\n      \"Define a scenario targeting customers who used vouchers in weeks 1-9 but not since week 10.\",\n      \"Trigger personalized emails or SMS with a new time-limited voucher and/or messaging about ongoing incentives.\",\n      \"Monitor reactivation and payment type preferences of re-engaged customers.\"\n    ],\n    \"estimatedImpact\": {\n      \"range\": \"high (potential to recover up to 8% of lost orders)\",\n      \"rangeUsd\": {\n        \"low\": 25000,\n        \"high\": 80000\n      },\n      \"assumption\": \"Assumes recovery of 20-65% of lost voucher user purchase value over the next month; number derived from baseline order drop and typical voucher-driven order value.\"\n    },\n    \"confidence\": \"high\",\n    \"effort\": \"medium\",\n    \"timeToSetUpMinutes\": 120,\n    \"readResultInDays\": 14,\n    \"prerequisites\": [\n      {\n        \"label\": \"Ability to identify customers who used vouchers in weeks 1-9\",\n        \"satisfied\": true\n      },\n      {\n        \"label\": \"Active voucher pool to assign new codes\",\n        \"satisfied\": false\n      },\n      {\n        \"label\": \"Automated messaging channel configured\",\n        \"satisfied\": true\n      }\n    ],\n    \"successMetric\": \"Order count for former voucher users: baseline ~12,500 orders per 9 weeks vs. target recovery of 4,000+ incremental orders in 4 weeks\"\n  },\n  {\n    \"title\": \"Segment and Analyze Voucher-Dependent Customers\",\n    \"rationale\": \"To tailor recovery efforts and long-term programs, cluster and analyze the cohort most affected - voucher users pre-week 10 - to understand their demographics, product categories, and payment alternatives.\",\n    \"bloomreachFeature\": \"segment\",\n    \"steps\": [\n      \"Create a segment of all customers who made a voucher payment in weeks 1-9 and none since week 10.\",\n      \"Analyze their order history, geolocation (SP, RJ, MG), and basket composition.\",\n      \"Surface insights for targeted marketing or product adjustments.\"\n    ],\n    \"estimatedImpact\": \"medium (enables improved targeting, likely indirect financial impact via future campaigns)\",\n    \"confidence\": \"medium\",\n    \"effort\": \"low\",\n    \"timeToSetUpMinutes\": 45,\n    \"readResultInDays\": 3,\n    \"prerequisites\": [\n      {\n        \"label\": \"Access to historical payment and customer data\",\n        \"satisfied\": true\n      }\n    ],\n    \"successMetric\": \"Segment created, >10,000 affected customers accurately identified; subsequent campaign conversion rate >10% above average\"\n  },\n  {\n    \"title\": \"Campaign: Communicate Voucher Program Changes and Alternatives\",\n    \"rationale\": \"Customer confusion over voucher policy changes may have contributed to order drop. A broadcast campaign clarifying changes, new incentives, or alternative payment benefits can ease friction and reduce churn.\",\n    \"bloomreachFeature\": \"campaign\",\n    \"steps\": [\n      \"Draft clear communication explaining reasons for voucher changes or expiry.\",\n      \"Offer incentives for alternative payments (e.g., installment plans, first purchase cashback).\",\n      \"Send campaign to all impacted voucher users and monitor engagement.\"\n    ],\n    \"estimatedImpact\": {\n      \"range\": \"low to moderate (~3-5% win-back of lost orders)\",\n      \"rangeUsd\": {\n        \"low\": 10000,\n        \"high\": 25000\n      },\n      \"assumption\": \"Assumes 25-40% open rate with 5-10% conversion among recipients.\"\n    },\n    \"confidence\": \"medium\",\n    \"effort\": \"low\",\n    \"timeToSetUpMinutes\": 60,\n    \"readResultInDays\": 7,\n    \"prerequisites\": [\n      {\n        \"label\": \"Up-to-date communication list of all affected users\",\n        \"satisfied\": true\n      },\n      {\n        \"label\": \"Clarity on voucher program changes and new offers\",\n        \"satisfied\": false\n      }\n    ],\n    \"successMetric\": \"Open rate > 25%, click-through > 5%, incremental orders attributable to campaign > 400 within two weeks\"\n  }\n]\n```"
+        }
+      ],
+      "usage": {
+        "inputTokens": 1052,
+        "outputTokens": 950,
+        "estimated": true
+      },
+      "model": "promoted-openai-replay"
+    }
+  ],
+  "eval": {
+    "requiredFields": [
+      "0.title",
+      "0.rationale",
+      "0.bloomreachFeature",
+      "0.steps",
+      "0.estimatedImpact",
+      "0.confidence"
+    ]
+  },
+  "promotion": {
+    "sourceArtifact": "artifacts/replays/2026-06-18T17-20-55-422Z-voucher-dropoff-w10-on-openai-studio.json",
+    "sourceProvider": {
+      "id": "openai",
+      "model": "gpt-4.1-2025-04-14"
+    },
+    "promotedAt": "2026-06-18T17:27:18.678Z",
+    "note": "This fixture captures the final replay answer deterministically; it does not reconstruct the live provider tool loop."
+  }
+}

package/node_modules/@aptkit/agent-recommendation/fixtures/sp-revenue-drop.json

@@ -0,0 +1,83 @@
+{
+  "id": "sp-revenue-drop-w4",
+  "description": "Fixture derived from Blooming Insights recommendation regression case 06-recommendation-sp.",
+  "workspace": {
+    "projectId": "olist",
+    "projectName": "Olist Brazilian ecommerce fixture",
+    "events": [
+      { "name": "order", "properties": ["state", "category", "purchase_ts", "price_brl"], "eventCount": 0 },
+      { "name": "payment", "properties": ["type", "installments", "value_brl"], "eventCount": 0 }
+    ],
+    "customerProperties": ["state", "city"],
+    "catalogs": [],
+    "totalCustomers": 0,
+    "totalEvents": 0,
+    "oldestTimestamp": null,
+    "dataHorizon": { "from": "2025-12-01", "to": "2026-06-01", "durationDays": 182 }
+  },
+  "anomaly": {
+    "metric": "revenue",
+    "scope": ["state:SP"],
+    "change": {
+      "value": 30,
+      "direction": "down",
+      "baseline": "week 4 (2025-12-22 to 2025-12-29) vs 12-week baseline"
+    },
+    "severity": "critical",
+    "evidence": [],
+    "impact": "Revenue for state:SP fell about 30% in a discrete window."
+  },
+  "diagnosis": {
+    "conclusion": "Sao Paulo state revenue fell about 30% in week 4 versus the surrounding baseline. The drop is isolated to SP and broad across categories, consistent with a localized demand or fulfillment factor.",
+    "evidence": [
+      "get_anomaly_context(metric=revenue, dimension=state, segment=SP) returned pct_change=-0.30 for week 4.",
+      "Related states RJ, MG, and PR stayed within normal variance.",
+      "Electronics, fashion, and home_decor were all down in SP week 4.",
+      "Order count fell while AOV stayed roughly flat, so the drop is volume-driven."
+    ],
+    "hypothesesConsidered": [
+      {
+        "hypothesis": "Single-category collapse drove the SP revenue drop",
+        "supported": false,
+        "reasoning": "All examined categories moved together."
+      },
+      {
+        "hypothesis": "Localized SP fulfillment or demand factor",
+        "supported": true,
+        "reasoning": "The issue is isolated to SP and volume-driven across categories."
+      }
+    ],
+    "affectedCustomers": {
+      "count": 4200,
+      "segmentDescription": "SP-state buyers in week 4 of dataset"
+    },
+    "confidence": "medium"
+  },
+  "tools": [
+    { "name": "list_scenarios", "description": "List existing automations", "inputSchema": { "type": "object" }, "result": { "data": [] } },
+    { "name": "list_segmentations", "description": "List existing segments", "inputSchema": { "type": "object" }, "result": { "data": [{ "name": "SP recent buyers" }] } },
+    { "name": "get_frequency_policies", "description": "List frequency policies", "inputSchema": { "type": "object" }, "result": { "data": [{ "name": "global weekly cap" }] } }
+  ],
+  "modelResponses": [
+    {
+      "content": [
+        { "type": "tool_use", "id": "tool-1", "name": "list_scenarios", "input": { "project_id": "olist" } }
+      ],
+      "usage": { "inputTokens": 850, "outputTokens": 45 },
+      "model": "fixture-model"
+    },
+    {
+      "content": [
+        {
+          "type": "text",
+          "text": "```json\n[{\"title\":\"Re-engagement campaign targeting lapsed SP buyers\",\"rationale\":\"Order count in SP fell while AOV held flat, so the fastest recovery lever is to reach full-value SP buyers who went quiet during the drop week.\",\"bloomreachFeature\":\"campaign\",\"steps\":[\"Build a segment of SP customers who purchased in the prior 8 weeks but not during the drop week.\",\"Send a localized re-engagement email with a soft incentive.\",\"Measure SP order count and revenue against the anomaly-week baseline.\"],\"estimatedImpact\":{\"range\":\"+$21k - $43k recovered revenue\",\"rangeUsd\":{\"low\":21000,\"high\":43000},\"assumption\":\"Assumes 10-20% reactivation of 4200 affected SP buyers.\"},\"effort\":\"low\",\"timeToSetUpMinutes\":45,\"readResultInDays\":7,\"prerequisites\":[{\"label\":\"email channel active\",\"satisfied\":true},{\"label\":\"SP customer property available\",\"satisfied\":true}],\"successMetric\":\"SP weekly order count returns to at least 95 orders within 7 days.\",\"confidence\":\"medium\"},{\"title\":\"Automated win-back scenario for SP buyers\",\"rationale\":\"The pattern may recur, so a triggered flow gives durable recovery infrastructure for SP customers who go silent.\",\"bloomreachFeature\":\"scenario\",\"steps\":[\"Trigger when state=SP and no order in 14 days after prior activity.\",\"Send a personalized win-back email.\",\"Escalate to a voucher follow-up if no purchase occurs.\"],\"estimatedImpact\":{\"range\":\"+$18k - $38k recovered revenue per recurrence\",\"rangeUsd\":{\"low\":18000,\"high\":38000},\"assumption\":\"Assumes 8-15% conversion among reachable lapsed SP buyers.\"},\"effort\":\"medium\",\"timeToSetUpMinutes\":90,\"readResultInDays\":14,\"prerequisites\":[{\"label\":\"triggered email channel active\",\"satisfied\":true}],\"successMetric\":\"Scenario conversion rate reaches at least 10% within 14 days.\",\"confidence\":\"medium\"}]\n```"
+        }
+      ],
+      "usage": { "inputTokens": 1200, "outputTokens": 550 },
+      "model": "fixture-model"
+    }
+  ],
+  "eval": {
+    "requiredFields": ["0.title", "0.rationale", "0.bloomreachFeature", "0.steps", "0.estimatedImpact", "0.confidence"]
+  }
+}

package/node_modules/@aptkit/agent-recommendation/fixtures/voucher-dropoff.json

@@ -0,0 +1,84 @@
+{
+  "id": "voucher-dropoff-w10-on",
+  "description": "Fixture derived from Blooming Insights recommendation regression case 08-recommendation-voucher.",
+  "workspace": {
+    "projectId": "olist",
+    "projectName": "Olist Brazilian ecommerce fixture",
+    "events": [
+      { "name": "order", "properties": ["state", "category", "purchase_ts", "price_brl"], "eventCount": 0 },
+      { "name": "payment", "properties": ["type", "installments", "value_brl"], "eventCount": 0 }
+    ],
+    "customerProperties": ["state", "city"],
+    "catalogs": [],
+    "totalCustomers": 0,
+    "totalEvents": 0,
+    "oldestTimestamp": null,
+    "dataHorizon": { "from": "2025-12-01", "to": "2026-06-01", "durationDays": 182 }
+  },
+  "anomaly": {
+    "metric": "payment_value",
+    "scope": ["payment_type:voucher"],
+    "change": {
+      "value": 95,
+      "direction": "down",
+      "baseline": "weeks 10-26 vs weeks 1-9 baseline"
+    },
+    "severity": "critical",
+    "evidence": [],
+    "impact": "Voucher payment value collapsed to about 5% of baseline and stayed depressed."
+  },
+  "diagnosis": {
+    "conclusion": "Voucher payment volume collapsed to roughly 5% of baseline starting week 10 and remained depressed through the end of the data horizon. Credit card and boleto did not absorb the lost volume, and order count fell, so this is likely a program-level voucher change rather than clean substitution.",
+    "evidence": [
+      "get_anomaly_context(metric=payment_value, dimension=payment_type, segment=voucher) returned pct_change=-0.95 for weeks 10-26.",
+      "Credit_card and boleto did not rise enough to absorb the lost voucher volume.",
+      "Total order_count was about 8% below baseline after the voucher cliff.",
+      "The drop was uniform across SP, RJ, and MG."
+    ],
+    "hypothesesConsidered": [
+      {
+        "hypothesis": "Voucher volume substituted to credit card or boleto",
+        "supported": false,
+        "reasoning": "Other payment types did not rise and total order count fell."
+      },
+      {
+        "hypothesis": "Program-level voucher change",
+        "supported": true,
+        "reasoning": "The cliff-shaped onset and sustained cross-state impact fit suspension, expiry, or restriction."
+      }
+    ],
+    "affectedCustomers": {
+      "count": 12500,
+      "segmentDescription": "Customers who previously used voucher payment in weeks 1-9"
+    },
+    "confidence": "medium"
+  },
+  "tools": [
+    { "name": "list_voucher_pools", "description": "List voucher pools", "inputSchema": { "type": "object" }, "result": { "data": [] } },
+    { "name": "list_email_campaigns", "description": "List email campaigns", "inputSchema": { "type": "object" }, "result": { "data": [{ "name": "inactive customer broadcast" }] } },
+    { "name": "get_frequency_policies", "description": "List frequency policies", "inputSchema": { "type": "object" }, "result": { "data": [{ "name": "one marketing message per week" }] } }
+  ],
+  "modelResponses": [
+    {
+      "content": [
+        { "type": "tool_use", "id": "tool-1", "name": "list_voucher_pools", "input": { "project_id": "olist" } },
+        { "type": "tool_use", "id": "tool-2", "name": "get_frequency_policies", "input": { "project_id": "olist" } }
+      ],
+      "usage": { "inputTokens": 940, "outputTokens": 75 },
+      "model": "fixture-model"
+    },
+    {
+      "content": [
+        {
+          "type": "text",
+          "text": "```json\n[{\"title\":\"Launch replacement incentive campaign for prior voucher users\",\"rationale\":\"The voucher program appears blocked and part of the former voucher cohort stopped ordering. A replacement incentive on boleto or credit card gives the merchant a fast retention path while the voucher root cause is resolved.\",\"bloomreachFeature\":\"campaign\",\"steps\":[\"Build a segment of customers who used voucher payment in weeks 1-9 and have not ordered since week 10.\",\"Create a 5% replacement incentive valid on boleto or credit card.\",\"Send a broadcast with a 10% holdout to measure incremental recovery.\"],\"estimatedImpact\":{\"range\":\"+$140k - $280k recovered over 28 days\",\"rangeUsd\":{\"low\":140000,\"high\":280000},\"assumption\":\"Assumes 10-20% reactivation of 12500 affected customers at the historical AOV.\"},\"effort\":\"medium\",\"timeToSetUpMinutes\":90,\"readResultInDays\":28,\"prerequisites\":[{\"label\":\"new voucher or discount pool exists\",\"satisfied\":false},{\"label\":\"email campaign channel available\",\"satisfied\":true}],\"successMetric\":\"Dormant voucher cohort reactivation reaches 10-20% within 28 days.\",\"confidence\":\"medium\"},{\"title\":\"Escalate voucher-program root cause with a status scenario\",\"rationale\":\"No marketing message fixes a program-level voucher outage. A structured escalation and customer-status segment makes the operational fix trackable and prevents the agent from treating policy failure as a campaign-only problem.\",\"bloomreachFeature\":\"scenario\",\"steps\":[\"Create a segment of customers affected by the voucher cliff.\",\"Route the week-10 cliff evidence to the voucher program owner.\",\"If voucher pools are restored, trigger a relaunch message to affected customers.\"],\"estimatedImpact\":{\"range\":\"Up to full voucher-channel recovery if the program is restored\",\"assumption\":\"Bounds the upside against pre-week-10 voucher payment value.\"},\"effort\":\"high\",\"timeToSetUpMinutes\":240,\"readResultInDays\":7,\"prerequisites\":[{\"label\":\"voucher program owner identified\",\"satisfied\":false},{\"label\":\"frequency policy available\",\"satisfied\":true}],\"successMetric\":\"Program status confirmed within 7 days with re-enable date or replacement-program decision.\",\"confidence\":\"high\"}]\n```"
+        }
+      ],
+      "usage": { "inputTokens": 1420, "outputTokens": 590 },
+      "model": "fixture-model"
+    }
+  ],
+  "eval": {
+    "requiredFields": ["0.title", "0.rationale", "0.bloomreachFeature", "0.steps", "0.estimatedImpact", "0.confidence"]
+  }
+}

package/node_modules/@aptkit/agent-recommendation/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@aptkit/agent-recommendation",
+  "version": "0.0.0",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "README.md",
+    "dist/src",
+    "fixtures"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test dist/test/*.test.js && node ../../../scripts/replay-promoted-fixtures.mjs --count recommendationCount",
+    "replay:fixture": "npm run build && node dist/scripts/replay-fixture.js",
+    "replay:promoted": "npm run build && node ../../../scripts/replay-promoted-fixtures.mjs --count recommendationCount"
+  },
+  "dependencies": {
+    "@aptkit/context": "0.0.0",
+    "@aptkit/evals": "0.0.0",
+    "@aptkit/prompts": "0.0.0",
+    "@aptkit/runtime": "0.0.0",
+    "@aptkit/tools": "0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0"
+  }
+}

package/node_modules/@aptkit/context/README.md

@@ -0,0 +1,15 @@
+# @aptkit/context
+
+Shared context builders for data-backed AptKit capabilities.
+
+This package owns the provider-neutral `WorkspaceDescriptor` shape and deterministic
+workspace summary rendering used by agents, prompt previews, and replay provenance.
+
+```ts
+import { schemaSummary, type WorkspaceDescriptor } from '@aptkit/context';
+
+const summary = schemaSummary(workspace);
+```
+
+Use capability-specific adapters outside this package to fetch or cache workspace
+metadata. This package should stay deterministic and fixture-friendly.

package/node_modules/@aptkit/context/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from './workspace-descriptor.js';
+export * from './workspace-summary.js';