# Manufacturing Traceability Intelligence Platform

GraphRAG-powered agentic AI platform for manufacturing traceability using Neo4j, Amazon Bedrock, and MCP.

## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                    INGESTION & ENRICHMENT LAYER                      │
│  Connectors → Chunking → Embeddings → Entity Extraction →           │
│  Entity Resolution → Graph Construction                              │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────────┐
│                    KNOWLEDGE GRAPH (Neo4j)                           │
│  Product → Requirement → Component → TestCase → TestRun →           │
│  Defect → ChangeRequest                                              │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────────┐
│                    RETRIEVAL LAYER                                   │
│  VectorRetriever │ GraphRAGRetriever │ NL2CypherRetriever │ Hybrid  │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────────┐
│                    AGENT LAYER                                       │
│  LangGraph Agent (plan→retrieve→reason→validate→respond)            │
│  Strands Agent (tool-calling with 5 specialized graph tools)        │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────────┐
│                    INTERFACE LAYER                                   │
│  FastAPI REST │ MCP Server (Claude Desktop / Cursor compatible)     │
└─────────────────────────────────────────────────────────────────────┘
```

## Quick Start

### 1. Prerequisites
- Neo4j 5.x (with APOC plugin)
- Python 3.11+
- AWS credentials with Bedrock access (Claude 3.5 Sonnet + Titan Embed v2)

### 2. Setup
```bash
cd manufacturing-graphrag
python -m venv .venv
.venv\Scripts\activate          # Windows
pip install -r requirements.txt
python -m spacy download en_core_web_sm
copy .env.example .env          # Edit with your credentials
```

### 3. Start Neo4j (Docker)
```bash
docker-compose up neo4j -d
```

### 4. Seed the Knowledge Graph
```bash
set PYTHONPATH=src
python scripts/seed_data.py
```

### 5. Start the Platform
```bash
# API server
python main.py api

# MCP server (for Claude Desktop)
python main.py mcp

# Both
python main.py all
```

### 6. Ingest Documents
```bash
python scripts/ingest.py path/to/spec.pdf path/to/requirements.csv
```

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Health check |
| GET | `/graph/stats` | Node counts by label |
| POST | `/ingest/file` | Upload and ingest a document |
| POST | `/ingest/record` | Ingest a structured API record |
| POST | `/query` | Hybrid GraphRAG query |
| POST | `/agent/langgraph` | LangGraph reasoning agent |
| POST | `/agent/strands` | Strands tool-calling agent |
| GET | `/traceability/defect/{id}` | Full defect traceability chain |
| GET | `/traceability/product/{id}` | Product traceability summary |

## Example Queries

```bash
# Hybrid GraphRAG query
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"question": "What components are affected by the thermal runaway defect?"}'

# LangGraph agent — multi-step reasoning
curl -X POST http://localhost:8000/agent/langgraph \
  -d '{"question": "Trace the full impact chain of DEF-001 and identify all change requests needed"}'

# Strands agent — tool-calling
curl -X POST http://localhost:8000/agent/strands \
  -d '{"question": "Which critical defects are blocking the EV BMS release?"}'

# Defect traceability
curl http://localhost:8000/traceability/defect/DEF-002
```

## MCP Integration (Claude Desktop)

Copy `config/claude_desktop_mcp.json` content into your Claude Desktop `claude_desktop_config.json`.

Available MCP tools:
- `ask_manufacturing_ai` — hybrid GraphRAG Q&A
- `semantic_search` — vector similarity search
- `graph_trace` — graph traversal retrieval
- `natural_language_to_cypher` — NL2Cypher
- `get_defect_chain` — full defect traceability
- `get_requirement_traceability` — requirement coverage
- `product_health_dashboard` — product metrics

## Knowledge Graph Schema

```
(Product)-[:HAS_REQUIREMENT]->(Requirement)
(Component)-[:IMPLEMENTS]->(Requirement)
(TestCase)-[:VALIDATES]->(Requirement)
(TestRun)-[:INSTANCE_OF]->(TestCase)
(TestRun)-[:FOUND_IN]->(Defect)
(Defect)-[:AFFECTS]->(Component)
(Defect)-[:TRIGGERS_CHANGE]->(ChangeRequest)
(ChangeRequest)-[:MODIFIES]->(Component)
(Document)-[:CONTAINS_CHUNK]->(Chunk)
(Chunk)-[:MENTIONS]->(any entity)
```

## Running Tests
```bash
set PYTHONPATH=src
pytest tests/ -v
```