# Industrial MCP Agent Platform

제조 데이터, 설비 이벤트, MES/ERP/품질/정비 tool을 하나의 MCP-compatible Agent 실행 경계로 묶는 산업 운영 AI 백엔드입니다.

LLM Agent를 단순 질의응답으로 두지 않고, 현장 데이터 연동과 운영 추적이 가능한 제품으로 만들기 위해 다음 문제를 제품 경계로 다룹니다.

- 설비 이벤트가 어떤 source system에서 들어왔는가
- 이벤트가 어떤 asset, work order, lot, material과 연결되는가
- Agent가 어떤 문서를 근거로 판단했는가
- MES/ERP 조회와 품질/정비 쓰기 작업을 어떻게 분리하는가
- 위험 tool call은 어디에서 approval-required 상태로 전환되는가
- 운영자는 incident triage, audit event, scenario run으로 실행을 재구성할 수 있는가

## 이 제품이 하는 일

한 줄로 정리하면, **제조 이벤트를 받아서 Agent가 근거 문서와 업무 시스템 tool을 함께 사용해 운영 판단을 만들고, 위험한 실행은 승인 대기로 통제하는 백엔드**입니다.

대표 흐름은 다음과 같습니다.

```text
설비/QMS/MES 이벤트 적재
-> 산업 운영 summary 계산
-> incident triage
-> 정비/품질/운영 문서 RAG 검색
-> MES/ERP read tool 호출
-> 정비 ticket/lot hold write tool approval-required 전환
-> 운영자 승인 또는 반려
-> audit event, timeline, dashboard 추적
```

예를 들어 `LINE-7-PRESS-02` 설비에서 온도 critical 이벤트가 들어오면 이 시스템은 다음을 처리합니다.

- 이벤트를 `industrial_event`로 저장한다.
- critical 이벤트 수와 영향을 받은 설비를 summary로 보여준다.
- 최근 이벤트를 묶어 원인 후보와 권장 조치를 만든다.
- 정비 기준 문서를 근거로 Agent 답변을 만든다.
- `maintenance.ticket.create` 요청은 즉시 실행하지 않고 승인 대기로 넘긴다.
- 승인/반려/replay 결과를 audit event로 남긴다.

## 문서

- [기능 설명과 사용 흐름](docs/FEATURES_AND_USAGE.md)
- [제품 전략](docs/PRODUCT_STRATEGY.md)
- [아키텍처](docs/ARCHITECTURE.md)
- [API 설계](docs/API_DESIGN.md)
- [DB 설계](docs/DATABASE_DESIGN.md)
- [디자인 패턴](docs/DESIGN_PATTERNS.md)

## 10분 사용 흐름

### 1. 설치와 실행

```bash
make install
make dev
```

기본 주소:

```text
http://127.0.0.1:8000
```

다른 포트가 필요하면 직접 실행합니다.

```bash
. .venv/bin/activate
uvicorn apps.api.main:app --host 127.0.0.1 --port 8014
```

확인:

```bash
curl -sS http://127.0.0.1:8014/health
```

### 2. 설비 이벤트 적재

```bash
curl -sS -X POST http://127.0.0.1:8014/v1/industrial/events \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant_id": "demo",
    "source_system": "opc-ua",
    "asset_id": "LINE-7-PRESS-02",
    "event_type": "temperature.threshold.exceeded",
    "severity": "critical",
    "payload": {
      "temperature_c": 91.4,
      "work_order_id": "WO-DEMO-001"
    }
  }'
```

### 3. 운영 요약과 triage 확인

```bash
curl -sS 'http://127.0.0.1:8014/v1/industrial/operations/summary?tenant_id=demo'
```

```bash
curl -sS -X POST http://127.0.0.1:8014/v1/industrial/incidents/triage \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant_id": "demo",
    "asset_id": "LINE-7-PRESS-02"
  }'
```

### 4. 문서 적재

```bash
curl -sS -X POST http://127.0.0.1:8014/v1/documents/ingest \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant_id": "demo",
    "title": "프레스 라인 정비 기준",
    "content": "LINE-7-PRESS-02 설비는 온도 90도를 초과하면 critical event로 분류한다. critical event가 발생하면 cooling 상태, 부하 상태, 최근 정비 이력을 함께 확인한다.",
    "source_type": "manual",
    "source_uri": "manual://press-line-maintenance",
    "classification": "internal"
  }'
```

### 5. Agent 실행과 approval-required 확인

```bash
curl -sS -X POST http://127.0.0.1:8014/v1/agents/runs \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant_id": "demo",
    "scenario": "production-incident-triage",
    "message": "LINE-7-PRESS-02 설비에 대한 정비 ticket 생성을 처리해줘",
    "actor_scopes": ["industrial:read", "maintenance:write"]
  }'
```

이 요청은 `maintenance.ticket.create` write tool로 라우팅되고, 바로 실행되지 않고 `approval_required` 상태가 됩니다.

승인 대기 조회:

```bash
curl -sS 'http://127.0.0.1:8014/v1/approvals/pending?tenant_id=demo'
```

승인:

```bash
curl -sS -X POST http://127.0.0.1:8014/v1/approvals/{approval_id}/approve \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant_id": "demo",
    "approved_by": "operator-01"
  }'
```

### 6. 한 번에 전체 흐름 검증

```bash
make demo
```

`make demo`는 sample document ingest, 산업 이벤트 적재, operations summary, incident triage, Agent run, feedback, diagnostics, evidence bundle, replay, approval-required action, scenario run을 한 번에 실행합니다.

## 제품 경계

```text
Manufacturing Gateway / MCP Client / Dashboard / REST API
        |
        v
FastAPI Router
        |
        v
Application Use Case
        |
        v
Domain Model / Policy
        |
        v
Port Interface
        |
        v
Adapter: Postgres, Vector DB, MES, ERP, QMS, Maintenance, Webhook
```

핵심 원칙은 제조 도메인 규칙과 외부 시스템 연동을 분리하는 것입니다.  
MES, ERP, QMS, 정비 시스템은 바뀔 수 있지만, 이벤트 수집, incident triage, approval, audit, evaluation 모델은 제품의 중심에 남습니다.

## 현재 구현 범위

- FastAPI 기반 REST API
- MCP-compatible JSON-RPC tool boundary
- 산업 이벤트 적재 API
- 설비/asset 기준 이벤트 필터링
- 산업 운영 summary API
- 산업 incident triage API
- 문서 적재, chunking, RAG 검색
- Ontology graph read model
- MES 작업지시 조회 tool
- ERP 재고/대체 자재 조회 tool
- 정비 ticket 생성 tool
- 품질 lot hold 요청 tool
- Tool Schema Registry
- required scope 기반 tool 실행 제어
- read tool 즉시 실행
- write tool approval-required 전환
- 승인/반려/replay API
- Tool Gateway timeout/retry/fallback/circuit breaker
- Agent 실행 trace
- audit event와 request id correlation
- webhook outbox와 dispatcher
- operations summary/SLO/alerts/dashboard
- production incident scenario runbook
- quality lot hold scenario runbook
- evaluation run과 regression gate
- Docker Compose 기반 로컬 인프라
- ruff, mypy, pytest 기반 검증

## 산업 도메인 API

```text
POST /v1/industrial/events
GET  /v1/industrial/events
GET  /v1/industrial/operations/summary
POST /v1/industrial/incidents/triage
```

예시 이벤트:

```json
{
  "tenant_id": "default",
  "source_system": "opc-ua",
  "asset_id": "LINE-7-PRESS-02",
  "event_type": "temperature.threshold.exceeded",
  "severity": "critical",
  "payload": {
    "temperature_c": 91.4,
    "work_order_id": "WO-DEMO-001"
  }
}
```

Incident triage 결과는 다음 정보를 반환합니다.

```text
severity
affected_assets
linked_event_ids
root_cause_hints
recommended_actions
required_agent_scopes
```

## MCP Tool Catalog

| Tool | Type | Scope | 목적 |
| --- | --- | --- | --- |
| `mes.work-order.lookup` | read | `industrial:read` | MES 작업지시와 설비 생산 상태 조회 |
| `erp.inventory.lookup` | read | `industrial:read` | ERP 재고와 대체 자재 가능성 조회 |
| `maintenance.ticket.create` | write | `maintenance:write` | 설비 이상 정비 ticket 생성 요청 |
| `quality.lot-hold.request` | write | `quality:write` | 품질 이상 lot hold 요청 |

쓰기성 tool은 바로 실행하지 않습니다. Agent 실행 중 `approval_required` 상태로 전환하고, 운영자가 승인하면 replay합니다.

## 기본 Scenario Runbook

```text
production-incident-triage
quality-lot-hold
```

각 scenario는 RAG 근거 확인, MCP tool 조회, 승인 필요 tool 실행을 하나의 흐름으로 검증합니다.

## 기술 스택

| 영역 | 선택 |
| --- | --- |
| API | Python 3.12+, FastAPI |
| Agent Runtime | Use case orchestration, LangGraph dependency boundary |
| RAG | query classification, retrieval strategy, citation |
| MCP | JSON-RPC compatible `/mcp` endpoint |
| Vector Search | local keyword adapter, Qdrant adapter |
| Persistence | in-memory adapter, Postgres adapter |
| Industrial Data | event ingestion, asset filter, incident triage |
| Tooling | MES/ERP/QMS/Maintenance tool registry |
| Governance | PII redaction, policy guard, approval-required action |
| Reliability | timeout, retry, fallback, circuit breaker |
| Observability | request id, process time header, trace step, audit event |
| Integration | webhook subscription, audit event outbox |
| Quality Gate | ruff, mypy, pytest, regression evaluation |

## 전체 API

```text
GET  /health
GET  /dashboard
GET  /v1/readiness

POST /v1/industrial/events
GET  /v1/industrial/events
GET  /v1/industrial/operations/summary
POST /v1/industrial/incidents/triage

POST /v1/documents/ingest
GET  /v1/documents
POST /v1/knowledge/search

POST /v1/agents/runs
POST /v1/agents/runs/preview
GET  /v1/agents/runs
GET  /v1/agents/runs/{run_id}
GET  /v1/agents/runs/{run_id}/timeline
GET  /v1/agents/runs/{run_id}/diagnostics
GET  /v1/agents/runs/{run_id}/evidence
POST /v1/agents/runs/{run_id}/feedback
POST /v1/agents/runs/{run_id}/replay

GET  /v1/ontology/graph
GET  /v1/audit/events
GET  /v1/audit/export

GET  /v1/operations/summary
GET  /v1/operations/usage
GET  /v1/operations/slo
GET  /v1/operations/incidents/snapshot
GET  /v1/operations/feedback/summary
GET  /v1/operations/alerts
GET  /v1/operations/migrations/status

GET  /v1/scenarios
GET  /v1/scenarios/runs
GET  /v1/scenarios/{scenario_id}
POST /v1/scenarios/{scenario_id}/run

GET  /v1/tools
GET  /v1/tools/gateway/status
POST /mcp

GET  /v1/approvals/pending
POST /v1/approvals/{approval_id}/approve
POST /v1/approvals/{approval_id}/reject
```

## 빠른 실행

```bash
make install
make dev
```

Swagger:

```text
http://127.0.0.1:8000/docs
```

Operator dashboard:

```text
http://127.0.0.1:8000/dashboard
```

서버 없이 전체 흐름을 검증할 수도 있습니다.

```bash
make demo
make verify
```

## 로컬 기본 모드

`.env` 없이 실행하면 다음 모드로 동작합니다.

```text
STORAGE_BACKEND=memory
VECTOR_BACKEND=local
```

이 모드는 외부 DB 없이 산업 이벤트 적재, RAG, MCP tool, approval, audit, scenario run을 검증하기 위한 모드입니다.

Postgres/Qdrant를 붙이면 같은 port 경계 위에서 저장소와 Vector DB adapter를 교체합니다.