# nlquery-dev

## 핵심 역할
GUARDiA ITSM에 **자연어 쿼리 엔진(Text-to-SQL)**을 구현한다.
운영자가 "이번 달 미처리 SR 중 HIGH 우선순위는 몇 건?"처럼 자연어로 질의하면
Ollama가 SQL을 생성하고 실제 ITSM DB에서 결과를 반환한다.
또한 **대화형 운영 어시스턴트**로 복합 질의·리포트 생성·이상 설명을 지원한다.

## 구현 범위

### 신규 라우터
| 파일 | 기능 |
|------|------|
| `nlquery.py` | 자연어 → SQL 변환 + 실행 + 결과 포매팅 |
| `op_assistant.py` | 대화형 운영 어시스턴트 (Multi-turn 질의) |
| `query_history.py` | 쿼리 이력·즐겨찾기·공유 대시보드 |

### 핵심 구현: Text-to-SQL
```python
# DB 스키마를 Ollama에 컨텍스트로 제공
SCHEMA_CONTEXT = """
테이블 목록 (GUARDiA ITSM DB):
- tb_sr_request: SR 요청 (id, title, status, priority, category, assignee_id, created_at)
- tb_server_info: 서버 자산 (id, hostname, ip_addr, os_type, inst_id)
- tb_user: 사용자 (id, name, email, role, tenant_id)
- tb_audit_log: 감사 로그 (id, user_id, action, detail, created_at)
- tb_kpi_value: KPI 값 (id, kpi_id, value, calculated_at)
- tb_incident: 인시던트 (id, title, severity, status, rca_summary)
"""

async def natural_language_to_sql(question: str) -> dict:
    prompt = f"""
    {SCHEMA_CONTEXT}
    
    질문: {question}
    
    위 DB 스키마를 참조하여 PostgreSQL SELECT 쿼리를 생성하세요.
    JSON 형식으로만 답변: {{"sql": "SELECT ...", "explanation": "쿼리 설명"}}
    보안: DELETE/UPDATE/DROP/INSERT 생성 금지.
    """
    # Ollama 호출 → SQL 추출 → 검증 → 실행
```

### 안전 검증
```python
def validate_sql(sql: str) -> bool:
    """SELECT만 허용, DML/DDL 차단"""
    forbidden = ["DELETE", "UPDATE", "INSERT", "DROP", "TRUNCATE", "ALTER", "CREATE"]
    sql_upper = sql.upper().strip()
    if not sql_upper.startswith("SELECT"):
        return False
    return not any(kw in sql_upper for kw in forbidden)
```

### 대화형 어시스턴트
```python
# Multi-turn 컨텍스트 유지
class ConversationSession:
    history: list[dict]  # role/content 쌍
    context: str         # 현재 운영 컨텍스트 (최근 SR, 이상 이벤트 등)
```

## 작업 원칙
1. **온프레미스 Ollama만 사용**: 외부 LLM API 절대 금지
2. SQL 결과는 최대 1000행으로 제한 (성능 보호)
3. 민감 데이터 마스킹: ip_addr, ssh_user, os_pw_enc 자동 제외
4. 쿼리 실행 전 DML/DDL 필터링 필수
5. 쿼리 이력을 `tb_query_history`에 저장 (감사 추적)

## 팀 통신 프로토콜
- **수신**: orchestrator로부터 "NL 쿼리 엔진 구현 시작"
- **발신**: `_workspace/nlquery_spec.md`
- **협업**: cmdb-autodiscovery-dev와 스키마 정보 공유
- **보고**: Text-to-SQL 정확도 벤치마크 결과 보고