Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions bench/oracle_view/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Oracle 뷰에 팀 지표 연결하기

이 데모는 한 행이 주문 한 건인 뷰에서 확정 주문의 순매출 합계를 조회합니다. 담당자는 숫자 컬럼, 날짜 컬럼, 집계 단위, 집계 방법, 필수 조건을 먼저 확인합니다. 지원 계약은 Oracle 일반 뷰 하나, NUMBER 컬럼의 SUM, DATE 컬럼의 시작일 포함·종료일 제외 범위, 문자 컬럼의 등호 조건입니다. 조건이 없으면 `filters`에 빈 객체를 명시합니다. 뷰 로직의 업무 의미와 신뢰성은 등록 담당자가 검토해야 합니다. Oracle 함수·패키지·프로시저 연결은 후속 범위입니다.

## 빈 데모 DB 준비

아래 명령을 저장소 루트에서 실행합니다. fixture는 새 사용자 두 명과 합성 데이터만 생성하며, 같은 사용자가 이미 있으면 중단합니다. Oracle과 호환되는 Docker 엔진, uv, openssl이 필요합니다.

```sh
uv sync --extra oracle --extra tools --extra mcp
export ORACLE_PASSWORD="$(openssl rand -hex 18)"
docker run -d --rm --name l2s-view-demo -e ORACLE_PASSWORD -p 127.0.0.1:11522:1521 gvenzl/oracle-free:23.9-slim-faststart
until docker exec l2s-view-demo healthcheck.sh >/dev/null 2>&1; do sleep 3; done
docker cp bench/oracle_view/fixture.sql l2s-view-demo:/tmp/fixture.sql
docker exec l2s-view-demo bash -c 'sqlplus -s /nolog <<SQL
CONNECT / AS SYSDBA
ALTER SESSION SET CONTAINER=FREEPDB1;
@/tmp/fixture.sql "$ORACLE_PASSWORD"
SQL'
export LANG2SQL_DB_URL="oracle+oracledb://L2S_VIEW_READER:${ORACLE_PASSWORD}@127.0.0.1:11522/?service_name=FREEPDB1"
export LANG2SQL_DB_SCHEMA=l2s_view_owner
```

## 담당자 등록과 동료 조회

`--store`는 등록·조회 프로세스가 함께 사용하는 메타데이터 파일입니다. 기존 텍스트 정의가 정확히 일치해야 연결할 수 있습니다. 운영자가 CLI로 연결을 확정하며, 등록 시점과 조회 시점 모두 설정된 DB 계정의 권한을 사용합니다. 확인한 계약은 [contract.json](contract.json)에 있습니다.

```sh
export TERM_STORE="$(mktemp)"
definition='확정 주문의 할인·반품 차감액 합계'
uv run lang2sql-tools --store "$TERM_STORE" --org-id demo --team-id sales --user-id registrar call term_custom \
--args '{"term":"순매출","kind":"metric","layer":"team","definition":"확정 주문의 할인·반품 차감액 합계"}'
uv run lang2sql-tools --store "$TERM_STORE" --org-id demo --team-id sales --user-id registrar bind-oracle-view \
--term 순매출 --layer team --definition "$definition" --contract bench/oracle_view/contract.json
uv run lang2sql-tools --store "$TERM_STORE" --org-id demo --team-id sales --user-id colleague call run_sql \
--args '{"metric_term":"순매출","period_start":"2025-10-01","period_end":"2025-11-01"}'
```

10월 결과는 **118**입니다. 10월 1일 주문은 85, 10월 31일 23시 주문은 33입니다. 취소된 주문 999와 11월 1일 주문은 제외합니다. 9월은 25, 11월은 10, 주문이 없는 12월은 SQL SUM의 NULL입니다.

MCP에서는 동료가 새 세션에서 `resolve_business_terms({"terms":["순매출"]})`를 호출하고, 받은 `definition_check_id`와 두 날짜를 `run_sql`에 전달합니다. 뷰가 연결된 정의로 자유 SQL을 제출하면 중단합니다. 결과에는 정의·레이어·출처·조건·바인드 값·실행 SQL과 행이 들어갑니다. 에이전트가 사용자에게 보여주는 요약은 이 도구 결과보다 짧을 수 있습니다.

조직·팀·개인 우선순위는 기존 정의 조회 규칙을 따릅니다. DB 접속 경로와 서비스, 뷰 식별자·DDL 시각·정의·출력 컬럼이 바뀌면 운영자가 다시 확인하고 연결합니다. 메타데이터 파일이나 조직 ID만으로 DB 권한을 부여하지 않습니다. 기존 Markdown 용어 번들은 텍스트를 전달하며 새 환경에서 뷰 연결을 새로 확인해야 합니다. 이 기능은 명시적으로 해결한 업무 용어의 계약을 검사합니다. 임의 SQL의 업무 의미를 추론하는 일반 권한 통제 장치는 아닙니다.

## 실제 검증 결과

두 개의 별도 Oracle Free 23.9 인스턴스에 같은 fixture를 설치했습니다. 동료 계정으로 새 세션에서 네 달을 조회해 **4/4** 기대값을 확인했습니다. 다른 팀에서는 정의를 찾을 수 없었습니다. 동명 뷰를 둔 두 번째 DB, SELECT 권한 회수, 금액 컬럼 변경, 뷰 삭제를 각각 검사해 4회 모두 조회가 중단됐습니다. 감사 기록에서 성공한 지표 SQL 4건, 차단 4건, 원본 테이블 대체 실행 0건을 확인했습니다.

별도 자연어 실험은 GPT-4.1 mini(2025-04-14), 월별 질문 4개, 질문당 최대 8회 호출, 같은 조회 계정·DB·스키마 정보를 사용했습니다. 각 질문은 새로운 MCP 프로세스에서 실행했습니다. OpenAI API 키가 있는 환경에서 아래 명령으로 반복할 수 있습니다.

```sh
uv run python bench/oracle_view/evaluate.py > comparison.json
```

| 최종 설정, 각 4문항 | SQL 실행 | 기대 결과 일치 | 뷰 사용 | 원본 테이블 대체 | 모델 호출 | 자동 등록 시간 |
|---|---:|---:|---:|---:|---:|---:|
| 텍스트 정의 | 1 | 1 | 1 | 0 | 12 | 0.20초 |
| 같은 정의 + 뷰 연결 | 2 | 2 | 2 | 0 | 10 | 0.44초 |

[문항별 SQL·결과·모델 응답](results.json)에 실패도 포함했습니다. 텍스트 조건은 11월, 연결 조건은 9월과 12월에 정답을 냈습니다. 후속 답변을 제공한 담당자는 양쪽 모두 0명이었습니다. 텍스트 조건에서 해결되지 않은 3건, 연결 조건에서 2건은 모델이 사용자에게 기간이나 정의를 다시 확인하려 했습니다. 계정 권한 설정과 사람의 계약 검토 시간은 위 자동 등록 시간에 포함되지 않습니다.

예비 실행에서는 MCP 서버 안내를 클라이언트 프롬프트에 전달하지 않았을 때 두 조건 모두 0/4였습니다. 서버 안내를 전달하되 소유자 스키마를 지정하지 않은 실행은 텍스트 0/4, 연결 2/4였습니다. 작은 합성 데이터셋의 설정별 단일 실행이므로 고객 정확도나 시간 절감률을 추정할 수 없습니다.
9 changes: 9 additions & 0 deletions bench/oracle_view/contract.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"owner": "L2S_VIEW_OWNER",
"view": "V_NET_SALES",
"amount": "NET_AMOUNT",
"period": "BOOKED_ON",
"aggregation": "SUM",
"grain": "One row per order",
"filters": {"STATUS": "POSTED"}
}
171 changes: 171 additions & 0 deletions bench/oracle_view/evaluate.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,171 @@
"""Compare text and bound definitions over real stdio MCP sessions and the same Oracle data."""

import asyncio
import json
import os
import sys
import tempfile
import time
from pathlib import Path

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

from lang2sql.adapters.llm.openai_ import OpenAILLM
from lang2sql.core.types import Message, Role, ToolSpec

TERM = "순매출"
DEFINITION = "확정(POSTED) 주문의 총액에서 할인과 반품을 차감한 원화 합계. NULL 할인·반품은 0. 주문일 기준."
MODEL = "gpt-4.1-mini-2025-04-14"
CASES = [
("2025년 9월", 25),
("2025년 10월", 118),
("2025년 11월", 10),
("2025년 12월", None),
]
SYSTEM = """Use the tools to query Oracle and return the numeric answer (or NULL). Resolve all business terms first.
Use the returned contract for run_sql. A period_end is exclusive. Ask rather than invent definitions.
The reader has SELECT on L2S_VIEW_OWNER.ORDERS(DAY,GROSS,DISCOUNT,RETURNED,STATUS)
and L2S_VIEW_OWNER.V_NET_SALES(BOOKED_ON,NET_AMOUNT,STATUS)."""


async def question(path, month, expected, llm):
spec = StdioServerParameters(
command=sys.executable,
args=[
"-m",
"lang2sql.frontends.mcp.server",
"--store",
str(path),
"--user-id",
"colleague",
"--org-id",
"demo",
"--team-id",
"sales",
],
env={
"LANG2SQL_DB_URL": os.environ["LANG2SQL_DB_URL"],
"LANG2SQL_DB_SCHEMA": "l2s_view_owner",
},
)
messages = [Message(Role.SYSTEM, SYSTEM), Message(Role.USER, f"{month} 순매출은?")]
outcome = {
"question": messages[-1].content,
"expected": expected,
"calls": 0,
"executed": False,
"correct_result": False,
"used_view": False,
"raw_table": False,
"tool_calls": [],
}
async with stdio_client(spec) as transport, ClientSession(*transport) as client:
initialized = await client.initialize()
messages[0].content += "\n" + (initialized.instructions or "")
specs = [
ToolSpec(t.name, t.description or "", t.inputSchema)
for t in (await client.list_tools()).tools
if t.name in ("resolve_business_terms", "run_sql", "explore_schema")
]
for _ in range(8):
outcome["calls"] += 1
turn = await llm.complete(messages, specs)
messages.append(
Message(Role.ASSISTANT, turn.content, tool_calls=turn.tool_calls)
)
if not turn.tool_calls:
outcome["answer"] = turn.content

break
for call in turn.tool_calls:
outcome["tool_calls"].append(call.name)
result = await client.call_tool(call.name, call.arguments)
content = result.content[0].text
messages.append(
Message(Role.TOOL, content, name=call.name, tool_call_id=call.id)
)
if call.name == "run_sql" and not result.isError:
if content.startswith("{"):
evidence = json.loads(content)
sql = evidence["sql"]
values = list(evidence["rows"][0].values())
else:
rows, _, sql = content.partition("\nSQL: ")
lines = rows.splitlines()
values = [lines[3].strip()] if len(lines) == 4 else []
outcome.update(
executed=True,
sql=sql,
values=values,
used_view="V_NET_SALES" in sql.upper(),
raw_table="L2S_VIEW_OWNER.ORDERS" in sql.upper(),
correct_result=len(values) == 1
and (
str(values[0]) in ("None", "NULL")
if expected is None
else str(values[0]) == str(expected)
),
)
return outcome


async def main():
contract = Path(__file__).with_name("contract.json")
report = {"model": MODEL, "max_calls": 8, "conditions": {}}
with tempfile.TemporaryDirectory() as tmp:
for mode in ("text", "bound"):
path = Path(tmp) / (mode + ".sqlite")
common = [
"--store",
str(path),
"--user-id",
"registrar",
"--org-id",
"demo",
"--team-id",
"sales",
]
started = time.monotonic()
proc = await asyncio.create_subprocess_exec(
sys.executable,
"-m",
"lang2sql.frontends.cli.tools",
*common,
"call",
"term_custom",
"--args",
json.dumps({"term": TERM, "definition": DEFINITION, "kind": "metric"}),
stdout=asyncio.subprocess.DEVNULL,
)
if await proc.wait():
raise RuntimeError("definition save failed")
if mode == "bound":
proc = await asyncio.create_subprocess_exec(
sys.executable,
"-m",
"lang2sql.frontends.cli.tools",
*common,
"bind-oracle-view",
"--term",
TERM,
"--definition",
DEFINITION,
"--layer",
"team",
"--contract",
str(contract),
stdout=asyncio.subprocess.DEVNULL,
)
if await proc.wait():
raise RuntimeError("view confirmation failed")
setup = time.monotonic() - started
records = await asyncio.gather(
*(question(path, m, e, OpenAILLM(model=MODEL)) for m, e in CASES)
)
report["conditions"][mode] = {"setup_seconds": setup, "records": records}
print(json.dumps(report, ensure_ascii=False, indent=2))


if __name__ == "__main__":
asyncio.run(main())
20 changes: 20 additions & 0 deletions bench/oracle_view/fixture.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
-- Run as SYSTEM inside a fresh, disposable FREEPDB1. SQL*Plus argument 1 is the demo password.
WHENEVER SQLERROR EXIT SQL.SQLCODE
SET VERIFY OFF
CREATE USER L2S_VIEW_OWNER IDENTIFIED BY "&1";
CREATE USER L2S_VIEW_READER IDENTIFIED BY "&1";
GRANT CREATE SESSION TO L2S_VIEW_READER;
ALTER USER L2S_VIEW_OWNER QUOTA 2M ON USERS;
CREATE TABLE L2S_VIEW_OWNER.ORDERS (day DATE, gross NUMBER, discount NUMBER, returned NUMBER, status VARCHAR2(12));
INSERT ALL
INTO L2S_VIEW_OWNER.ORDERS VALUES (DATE '2025-09-30', 25, NULL, NULL, 'POSTED')
INTO L2S_VIEW_OWNER.ORDERS VALUES (DATE '2025-10-01', 100, 10, 5, 'POSTED')
INTO L2S_VIEW_OWNER.ORDERS VALUES (DATE '2025-10-31'+23/24, 40, NULL, 7, 'POSTED')
INTO L2S_VIEW_OWNER.ORDERS VALUES (DATE '2025-10-15', 999, NULL, NULL, 'CANCELLED')
INTO L2S_VIEW_OWNER.ORDERS VALUES (DATE '2025-11-01', 12, 2, NULL, 'POSTED')
SELECT 1 FROM dual;
CREATE VIEW L2S_VIEW_OWNER.V_NET_SALES AS
SELECT day AS booked_on, gross - NVL(discount,0) - NVL(returned,0) AS net_amount, status FROM L2S_VIEW_OWNER.ORDERS;
GRANT SELECT ON L2S_VIEW_OWNER.ORDERS TO L2S_VIEW_READER;
GRANT SELECT ON L2S_VIEW_OWNER.V_NET_SALES TO L2S_VIEW_READER;
EXIT
Loading