{"id":48135459,"url":"https://github.com/mongodb-industry-solutions/smf-yield-defect-detection","last_synced_at":"2026-04-04T16:45:34.882Z","repository":{"id":328933315,"uuid":"1048825995","full_name":"mongodb-industry-solutions/smf-yield-defect-detection","owner":"mongodb-industry-solutions","description":"MongoDB-powered semiconductor yield optimization with real-time analytics, wafer defect search and AI root cause analysis","archived":false,"fork":false,"pushed_at":"2026-03-24T14:41:13.000Z","size":2841,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"staging","last_synced_at":"2026-03-25T15:59:29.292Z","etag":null,"topics":["manufacturing","semiconductor","yield-analytics"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mongodb-industry-solutions.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-02T04:55:41.000Z","updated_at":"2026-03-24T14:28:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mongodb-industry-solutions/smf-yield-defect-detection","commit_stats":null,"previous_names":["mongodb-industry-solutions/smf-yield-defect-detection"],"tags_count":0,"template":false,"template_full_name":"mongodb-industry-solutions/agentic-framework","purl":"pkg:github/mongodb-industry-solutions/smf-yield-defect-detection","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongodb-industry-solutions%2Fsmf-yield-defect-detection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongodb-industry-solutions%2Fsmf-yield-defect-detection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongodb-industry-solutions%2Fsmf-yield-defect-detection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongodb-industry-solutions%2Fsmf-yield-defect-detection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mongodb-industry-solutions","download_url":"https://codeload.github.com/mongodb-industry-solutions/smf-yield-defect-detection/tar.gz/refs/heads/staging","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongodb-industry-solutions%2Fsmf-yield-defect-detection/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31405890,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["manufacturing","semiconductor","yield-analytics"],"created_at":"2026-04-04T16:45:32.237Z","updated_at":"2026-04-04T16:45:34.872Z","avatar_url":"https://github.com/mongodb-industry-solutions.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agentic Yield Analytics for Semiconductor Manufacturing\n\nDemonstrates how MongoDB Atlas's unified data platform — combining time series, vector search, and document flexibility — powers real-time defect detection and AI-driven root cause analysis in semiconductor manufacturing, where yield loss costs the industry $50B+ annually.\n\n## Where MongoDB Shines\n\n- **Time Series Collections**: MongoDB's native time series collections store high-frequency sensor telemetry (particle counts, RF power, temperature) from CMP, ETCH, and LITHO equipment with automatic bucketing and efficient temporal queries — no separate time series database needed.\n- **Change Streams for Real-Time Detection**: The Excursion Detector uses MongoDB Change Streams to monitor incoming sensor data in real time. When readings breach configurable thresholds, alerts fire within seconds — replacing batch jobs that traditionally take hours.\n- **Atlas Vector Search for Defect Matching**: Multimodal embeddings from Voyage AI encode both wafer defect images and text descriptions into a shared vector space. Atlas Vector Search finds similar historical defects by visual pattern, enabling \"show me defects that look like this\" queries without a separate vector database.\n- **Atlas Search for Knowledge Retrieval**: Full-text search over historical RCA reports, troubleshooting guides, and process context documents. The LangGraph agent uses this to pull relevant remediation steps during root cause analysis.\n- **Flexible Document Model**: Sensor readings, wafer defect maps, alert documents, agent conversation checkpoints, and knowledge base articles all live in the same cluster — each with its own natural schema. No impedance mismatch, no ETL pipelines between systems.\n- **LangGraph Agent Persistence**: MongoDB stores LangGraph checkpoints and conversation memory, giving the RCA agent durable state across sessions. Resume an investigation days later with full context intact.\n\n## High Level Architecture\n\n![Architecture Diagram](assets/architecture-diagram.png)\n\n## Solution Architecture\n\n![Solution Architecture Diagram](assets/solution-architecture.png)\n\nMongoDB Atlas serves as the unified data layer — storing time-series telemetry, vector embeddings, and operational documents in one platform. Change Streams push real-time alerts to the frontend, while LangGraph agents query the knowledge base for autonomous root cause analysis.\n\n### Data Flow\n\n1. **Machine telemetry** streams into MongoDB **Time Series Collections** (`process_sensor_ts`), with a regular collection (`sensor_events`) feeding Change Streams.\n2. The **Excursion Detection System** watches the stream via Change Streams. When a threshold is breached, it writes to three collections — **Knowledge Base** (`historical_knowledge`), **Wafer Defects** (`wafer_defects`), and **Alerts** (`alerts`).\n3. Alert creation triggers another **Change Stream** that notifies the **AI Agent** in real time — no polling required.\n4. The **LangGraph AI Agent** performs autonomous root cause analysis using four tools:\n   - **Query Alerts** — fetch active and recent alerts from MongoDB\n   - **Query Wafer Defects** — multimodal vector search over defect records\n   - **Query Time Series** — correlate sensor anomalies with defect events\n   - **Query Historical Knowledge** — semantic search over RCA reports and troubleshooting guides\n5. The agent uses **MongoDB Search + Vector Search + Hybrid Search** to find relevant context across all collections.\n6. **Voyage AI multimodal embeddings** (`voyage-multimodal-3`) encode both wafer defect images and text descriptions into a shared 1024-dimensional vector space, powering the similarity search.\n7. The **Chat Interface** communicates with the agent, with **Short Term Memory** (`checkpoints`) persisted in MongoDB so conversations survive across sessions.\n8. The agent produces an **Agentic Root Cause Report** with findings and actionable recommendations.\n\n### MongoDB Capabilities Used\n\n- **Vector Search \u0026 Hybrid Search** for semantic pattern matching across defect records and knowledge base\n- **Aggregation Framework** for complex data transformations and KPI calculations\n- **Voyage AI multimodal embeddings** for encoding defect images and manuals into a shared vector space\n- **Full Text Search** across operation logs, RCA reports, and process context documents\n- **Change Streams** for push-based real-time event propagation (sensor → excursion → alert → agent)\n- **Time Series Collections** for high-frequency sensor data with automatic bucketing\n\n## Tech Stack\n\n- **[MongoDB Atlas](https://www.mongodb.com/atlas)** for the unified data layer (time series telemetry, alerts, wafer defects, knowledge base, agent state)\n- **[MongoDB Atlas Vector Search](https://www.mongodb.com/docs/atlas/atlas-vector-search/)** for multimodal defect similarity matching (wafer images + text)\n- **[MongoDB Atlas Search](https://www.mongodb.com/docs/atlas/atlas-search/)** for full-text search across historical knowledge and process context\n- **[MongoDB Change Streams](https://www.mongodb.com/docs/manual/changeStreams/)** for real-time sensor anomaly detection\n- **[LangGraph](https://langchain-ai.github.io/langgraph/)** for the agentic RCA workflow (ReAct agent with tool use)\n- **[AWS Bedrock](https://aws.amazon.com/bedrock/)** (Anthropic Claude 3.5 Sonnet) for AI-powered root cause analysis\n- **[Voyage AI](https://www.voyageai.com/)** for multimodal embedding generation (voyage-multimodal-3)\n- **[Next.js 15](https://nextjs.org/)** App Router with React 19 for the frontend\n- **[FastAPI](https://fastapi.tiangolo.com/)** (Python) for the backend API with async Motor driver\n- **[LeafyGreen UI](https://github.com/mongodb/leafygreen-ui)** (MongoDB's design system) for frontend components\n- **[Chart.js](https://www.chartjs.org/)** for real-time sensor data visualizations\n- **[Socket.IO](https://socket.io/)** for live WebSocket communication between backend and dashboard\n\n## Prerequisites\n\nBefore you begin, ensure you have met the following requirements:\n\n- **Python 3.10** or higher\n- **Node.js 18** or higher (20.x recommended)\n- **uv** (install via [uv's official documentation](https://docs.astral.sh/uv/getting-started/installation/))\n- **MongoDB Atlas** cluster (M10 or higher for Atlas Vector Search)\n- **AWS credentials** with Bedrock access (for Claude 3.5 Sonnet)\n- **Voyage AI API key** for multimodal embedding generation (get one at [Voyage AI's dashboard](https://dash.voyageai.com/api-keys))\n- **Docker \u0026 Docker Compose** (optional, for containerized deployment)\n\n## Initial Configuration\n\n### Obtain Your MongoDB Connection String\n\n1. Set up a [MongoDB Atlas](https://www.mongodb.com/atlas) cluster if you don't have one already.\n2. Locate your cluster, click **Connect**, and select **Connect your application**.\n3. Copy the connection string.\n\n\u003e You'll need this connection string for the `MONGODB_URI` environment variable later.\n\n### Set Up AWS Bedrock Access\n\n1. Log in to the [AWS Management Console](https://aws.amazon.com/console/).\n2. Navigate to the **Bedrock** service (or search for \"Bedrock\" in the AWS search bar).\n3. Request access to the **Anthropic Claude 3.5 Sonnet** model if you haven't already.\n4. Either configure an IAM user with programmatic access (Access Key ID + Secret Access Key) or set up an AWS SSO profile with Bedrock permissions.\n\n\u003e Keep your AWS credentials secure and never commit them to version control.\n\n### Clone the Repository\n\n1. Open your terminal and navigate to the directory where you want to store the project:\n\n   ```bash\n   cd /path/to/your/desired/directory\n   ```\n\n2. Clone the repository:\n\n   ```bash\n   git clone \u003crepository-uri\u003e\n   ```\n\n3. Navigate into the cloned project:\n\n   ```bash\n   cd smf-yield-defect-detection\n   ```\n\n### Seed Data\n\nThe demo auto-seeds data on first launch. When you open the dashboard, it checks for existing data and runs the initialization automatically if needed. This creates:\n\n- Baseline sensor telemetry (time series data for CMP, ETCH, and LITHO equipment)\n- Wafer defect records with embedded images (multimodal Voyage AI embeddings)\n- Historical knowledge base documents (RCA reports, troubleshooting guides)\n- Process context documents (recipes, equipment configurations)\n\n\u003e No manual data import is required. The `/seed/initialize` endpoint handles everything, and the frontend calls it automatically on first load.\n\n### Create Atlas Vector Search Indexes\n\nThe system requires two Atlas Vector Search indexes for semantic similarity queries. Create these in the Atlas UI under **Database** → **Atlas Search**.\n\n**1. `wafer_defects_vector_search`** — Vector Search index on `wafer_defects`\n\nIndex name: `wafer_defects_vector_search`\n\n```json\n{\n  \"fields\": [\n    {\n      \"type\": \"vector\",\n      \"path\": \"embedding\",\n      \"numDimensions\": 1024,\n      \"similarity\": \"cosine\"\n    },\n    {\n      \"type\": \"filter\",\n      \"path\": \"defect_summary.defect_pattern\"\n    },\n    {\n      \"type\": \"filter\",\n      \"path\": \"defect_summary.severity\"\n    }\n  ]\n}\n```\n\n**2. `historical_knowledge_vector_search`** — Vector Search index on `historical_knowledge`\n\nIndex name: `historical_knowledge_vector_search`\n\n```json\n{\n  \"fields\": [\n    {\n      \"type\": \"vector\",\n      \"path\": \"embedding\",\n      \"numDimensions\": 1024,\n      \"similarity\": \"cosine\"\n    },\n    {\n      \"type\": \"filter\",\n      \"path\": \"document_type\"\n    },\n    {\n      \"type\": \"filter\",\n      \"path\": \"process_area\"\n    }\n  ]\n}\n```\n\n### Create Atlas Search Indexes\n\nThe system also uses Atlas Search (full-text) indexes for keyword-based queries.\n\n**3. `wafer_defects_text_index`** — Atlas Search index on `wafer_defects`\n\nIndex name: `wafer_defects_text_index`\n\n```json\n{\n  \"mappings\": {\n    \"dynamic\": true\n  }\n}\n```\n\n**4. `historical_knowledge_text_index`** — Atlas Search index on `historical_knowledge`\n\nIndex name: `historical_knowledge_text_index`\n\n```json\n{\n  \"mappings\": {\n    \"dynamic\": true\n  }\n}\n```\n\n#### How to Create Atlas Vector Search Indexes (indexes 1–2)\n\n1. Go to [Atlas](https://cloud.mongodb.com/) and select your cluster.\n2. Click **Atlas Search** in the left sidebar.\n3. Click **Create Search Index**.\n4. Select **Atlas Vector Search** as the index type, then click **Next**.\n5. Choose the **JSON Editor** for the configuration method.\n6. Select the target collection (e.g., `wafer_defects`).\n7. Set the **Index Name** (e.g., `wafer_defects_vector_search`).\n8. Replace the default definition with the JSON above for that index.\n9. Click **Next**, review the settings, then click **Create Search Index**.\n10. Repeat for the second vector search index.\n\n#### How to Create Atlas Search Indexes (indexes 3–4)\n\n1. From the **Atlas Search** page, click **Create Search Index**.\n2. Select **Atlas Search** as the index type, then click **Next**.\n3. Choose the **JSON Editor** for the configuration method.\n4. Select the target collection (e.g., `wafer_defects`).\n5. Set the **Index Name** (e.g., `wafer_defects_text_index`).\n6. Replace the default definition with the JSON above.\n7. Click **Next**, review, then click **Create Search Index**.\n8. Repeat for the second text search index.\n\n\u003e Indexes take a few seconds to build. Wait until the status shows **Active** before running the demo.\n\n## Run it Locally\n\n### Backend\n\n1. Navigate to the `backend` folder and install dependencies:\n\n   ```bash\n   cd backend\n\n   # Install UV package manager (if not already installed)\n   curl -LsSf https://astral.sh/uv/install.sh | sh\n\n   # Install dependencies\n   uv sync\n   ```\n\n2. Verify that the `.venv` folder has been generated within the `backend/` directory.\n\n3. Create a `.env` file in the `backend/` directory:\n\n   ```bash\n   MONGODB_URI=\n   MDB_DATABASE_NAME=\n   AWS_REGION=\n   AWS_ACCESS_KEY_ID=\n   AWS_SECRET_ACCESS_KEY=\n   VOYAGE_API_KEY=\n   ```\n\n   \u003e Alternatively, if you use AWS SSO, replace the access key variables with `AWS_PROFILE=\u003cyour-profile-name\u003e`.\n\n### Frontend\n\n1. Navigate to the `frontend` folder.\n\n2. Create a `.env` file:\n\n   ```bash\n   NEXT_PUBLIC_API_URL=/api/backend\n   INTERNAL_API_URL=http://127.0.0.1:8000\n   ```\n\n3. Install dependencies:\n\n   ```bash\n   npm install\n   ```\n\n### Running Locally\n\nAfter setting up both backend and frontend dependencies, start all services with:\n\n```bash\nmake dev\n```\n\nThis starts the backend (port 8000) and frontend (port 3000) together in the background.\n\n- **Frontend**: \u003chttp://localhost:3000\u003e\n- **Backend API**: \u003chttp://localhost:8000\u003e\n- **API Documentation**: \u003chttp://localhost:8000/docs\u003e\n\nYou can also run services separately:\n\n```bash\nmake dev-backend     # Backend (8000) only\nmake dev-frontend    # Frontend (3000) only\nmake dev-fg          # Both services in foreground (blocking)\n```\n\n**Useful commands:**\n\n```bash\nmake dev-logs          # Tail all service logs\nmake dev-logs-backend  # Tail backend logs only\nmake dev-logs-frontend # Tail frontend logs only\nmake stop              # Stop all services\nmake health            # Check if services are reachable\n```\n\n\u003e **Note:** If ports are already in use (e.g., by Docker containers), either stop the containers with `make down` or run `make stop` to free the ports.\n\n## Run with Docker\n\nMake sure to run this from the root directory.\n\nTo build and start all containers:\n\n```bash\nmake build\n```\n\nThis starts two containers:\n\n- **Frontend**: \u003chttp://localhost:3000\u003e\n- **Backend**: \u003chttp://localhost:8000\u003e\n\n\u003e The Docker setup mounts your local `~/.aws/credentials` into the backend container, so AWS SSO profiles work without setting explicit keys.\n\nTo stop and remove containers:\n\n```bash\nmake down\n```\n\nTo force rebuild from scratch:\n\n```bash\nmake rebuild\n```\n\nTo clean up all images and volumes:\n\n```bash\nmake clean\n```\n\n## Common Errors\n\n### Backend Errors\n\n- Check that you've created a `.env` file in `backend/` with a valid MongoDB URI, AWS credentials, and Voyage AI API key.\n- Ensure your MongoDB Atlas cluster has the four search indexes (2 vector + 2 text) created on the `wafer_defects` and `historical_knowledge` collections.\n- Verify AWS credentials have Bedrock model access for Claude 3.5 Sonnet (`us.anthropic.claude-3-5-sonnet-20241022-v2:0`).\n- If you see `VOYAGE_API_KEY not set` errors, ensure the key is in your `backend/.env` file.\n\n### Frontend Errors\n\n- Check that you've created a `.env` file in `frontend/` with `INTERNAL_API_URL` pointing to your running backend.\n- If LeafyGreen UI components fail to load, delete `node_modules` and run `npm install --legacy-peer-deps` again.\n- Ensure Node.js version is 18 or higher (`node --version`).\n\n### Seed Data Errors\n\n- If the dashboard shows a loading screen that never completes, check the backend logs (`make dev-logs-backend`) for connection errors.\n- The seed process generates Voyage AI embeddings for wafer images, which requires a valid `VOYAGE_API_KEY`. If embedding generation fails, wafer similarity search will not work.\n\n## Core Capabilities\n\nThe platform combines **real-time monitoring**, **semantic search**, and an **agentic RCA workflow** — all backed by MongoDB Atlas as the single data layer.\n\n### Real-Time Excursion Detection\n\nThe system continuously ingests sensor telemetry from CMP, ETCH, and LITHO manufacturing equipment into MongoDB time series collections. A Change Stream-based **Excursion Detector** watches for threshold breaches in real time:\n\n- **Particle Count** — Critical at \u003e2000 particles, High at \u003e1500, Medium at \u003e1000\n- **RF Power Drift** — Equipment-specific baselines (CMP: 1450W, ETCH: 1200W, LITHO: 800W) with drift thresholds\n- **Temperature Drift** — Equipment-specific baselines with severity tiers\n- **Yield Degradation** — Alerts when batch yield drops below 80% / 85% / 92%\n\nWhen a threshold is breached, an alert document is created in MongoDB and pushed to the dashboard via WebSocket within seconds.\n\n### Multimodal Defect Search\n\n![Multimodal Defect Search](assets/multimodal-defect-search.png)\n\nWafer defect records include both structured data (lot ID, equipment, yield percentage) and unstructured data (defect images, text descriptions). Voyage AI's multimodal model (`voyage-multimodal-3`) generates 1024-dimensional embeddings that encode both visual patterns and textual context into a shared vector space.\n\nAtlas Vector Search then enables queries like:\n- \"Find wafers with cluster defects similar to this one\"\n- \"Show me historical defects from CMP_TOOL_01 with edge patterns\"\n- Natural language descriptions that match against both image and text embeddings\n\n### Agentic Root Cause Analysis\n\n![Agentic Root Cause Analysis](assets/agent-root-cause-analysis.png)\n\nWhen the operator switches to Agentic mode, a **LangGraph ReAct agent** powered by Claude 3.5 Sonnet performs multi-step investigations. The agent has access to four tools:\n\n- **Query Alerts** — Fetch active and recent alerts from MongoDB, filtered by equipment or wafer ID\n- **Query Wafer Defects** — Multimodal vector search over wafer defect records, returning visually and textually similar historical cases\n- **Query Time Series Data** — Correlates sensor anomalies with defect events over time windows\n- **Query Historical Knowledge** — Semantic search over RCA reports, troubleshooting guides, and process documentation\n\nThe agent reasons step-by-step, decides which tools to call, and synthesizes findings into actionable recommendations — all streamed to the dashboard in real time via Server-Sent Events. MongoDB stores agent checkpoints so conversations persist across sessions.\n\n### Live Monitoring Dashboard\n\nThe dashboard provides three operational modes:\n\n- **Normal Mode** — Process Health Matrix showing equipment status, live sensor charts (particle count, RF power, temperature), real-time alerts panel, and wafer defect visualizations\n- **Search Mode** — Unified semantic search across all collections with vector, text, or hybrid search modes\n- **Agentic Mode** — Natural language chat interface for AI-powered root cause analysis with streaming responses\n\n## Additional Resources\n\n### MongoDB Resources\n\n- [MongoDB for Manufacturing](https://www.mongodb.com/solutions/industries/manufacturing)\n- [MongoDB Atlas](https://www.mongodb.com/atlas)\n- [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/atlas/atlas-vector-search/)\n- [MongoDB Atlas Search Documentation](https://www.mongodb.com/docs/atlas/atlas-search/)\n- [MongoDB Change Streams](https://www.mongodb.com/docs/manual/changeStreams/)\n- [MongoDB Time Series Collections](https://www.mongodb.com/docs/manual/core/timeseries-collections/)\n- [MongoDB LeafyGreen UI](https://github.com/mongodb/leafygreen-ui)\n\n### Frameworks and Services\n\n- [LangGraph](https://langchain-ai.github.io/langgraph/) — agentic workflow orchestration with tool use\n- [AWS Bedrock](https://aws.amazon.com/bedrock/) — managed LLM access (Anthropic Claude 3.5 Sonnet)\n- [Voyage AI](https://www.voyageai.com/) — multimodal embedding generation for vector search\n- [Next.js 15](https://nextjs.org/) — React framework with App Router\n- [FastAPI](https://fastapi.tiangolo.com/) — Python async API framework\n- [Chart.js](https://www.chartjs.org/) — JavaScript charting library\n- [Socket.IO](https://socket.io/) — real-time bidirectional communication\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmongodb-industry-solutions%2Fsmf-yield-defect-detection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmongodb-industry-solutions%2Fsmf-yield-defect-detection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmongodb-industry-solutions%2Fsmf-yield-defect-detection/lists"}