Packaging Sentinel

A managed-agent and deterministic replay framework for semiconductor advanced packaging and final-test excursion investigation.

This repository leverages Google Cloud's Agent Platform (running hosted Gemini models like antigravity-preview-05-2026) and static, physics-defensible data generators to identify, isolate, and recommend human-approved containment for manufacturing drift.

---

🚀 Quick Start

1. Requirements

• Node.js (v20.6+ recommended; uses native --env-file flags)
• Python 3.9+
• Google Cloud SDK (gcloud authenticated, if running live hosted agents)

2. Installation

Install NPM dependencies for the web dashboard and Cloudflare Workers API:

npm install

3. Generate Simulated Datasets

Synthesize physics-coherent semiconductor datasets (covering reflow, underfill, and electrical testcell scenarios):

python3 scripts/generate_osat_watchtower_data.py all

4. Run Deterministic Replays & Evaluation

Run the local state-machine simulation and score the accuracy of findings against the scenario ground truth:

# Replay and score the default scenario
python3 scripts/run_watchtower_simulation.py --scenario reflow
python3 scripts/evaluate_watchtower.py --scenario reflow

5. Launch the Dashboard

Serve the interactive frontend UI locally:

python3 scripts/managed_demo_server.py

Open your browser and navigate to http://localhost:8000 to interact with the visual telemetry, explore anomaly timelines, and trigger the live agent lanes.

---

🤖 Running the Live Managed Agent

To execute the live hosted Gemini agent rather than the pre-rendered local simulation, use the integrated Google Agent Platform wrapper:

1. Initialize the Session:

   bash scripts/run_managed_agent_hackathon_session.sh

2. Deploy the Agent Configuration:

   bash scripts/create_managed_watchtower_agent.sh

   This registers the agent osat-yield-watchtower configured with tool capabilities (Google Search, Python execution) and safe system guidelines.
3. Interact and Query:

   bash scripts/interact_managed_watchtower_agent.sh "Open an OSAT package-test drift incident and propose the first investigation plan."

---

🏛️ Project Directory Structure

├── agent_platform/      # System instructions and API setups for Hosted Gemini Agents
├── data/                # Generated physics-defensible dataset manifests and schema definitions
├── demo/                # Interactive web dashboard (HTML, CSS, JS) and static artifacts
├── docs/                # Research papers, yield economics model details, and architectural overviews
├── scripts/             # Simulation generators, evaluation suites, and daemon utilities
└── wrangler.toml        # Configuration file for Cloudflare Workers endpoint API

---

🔒 Safety and Guardrails

• No Autonomous Actions: To remain safe for production environments, the system never executes autonomous tool shutdowns or lot holds. All containment actions require explicit human approval.
• Ranked Hypotheses: The agent identifies probable root causes as "ranked hypotheses" backed by statistical confidence levels rather than asserting absolute certainty.