콘텐츠로 이동

Zio.ontology()

온톨로지를 만들고, 그 온톨로지대로 세웁니다. 둘 다 이 묶음입니다 — 앞엣것은 종이를 그리는 일이고, 뒤엣것은 그 종이대로 값을 넣는 일입니다.

TBox 와 ABox — 이 매뉴얼의 두 낱말

섹션 제목: “TBox 와 ABox — 이 매뉴얼의 두 낱말”
  • TBox(온톨로지) — 무엇이 있을 수 있는가: 노드 유형 · 관계 · 속성. Zio.ontology() 로 다룹니다.
  • ABox(지식 그래프) — 실제로 무엇이 있는가: 개별 노드 · 엣지 · 값. Zio.node() 로 다룹니다.

온톨로지를 고쳐도 이미 쌓인 지식 그래프는 다시 쓰지 않습니다(소급 적용 없음). twin_id = 온톨로지(TBox) 하나의 id. 그 TBox 의 시점은 version_tag(v1… · 현재판)입니다.

온톨로지에는 어떤 노드에 어떤 속성이 있고 무엇이 무엇과 이어지는지가 적혀 있습니다. 웹의 온톨로지 스키마 에디터에서 그리는 그 종이입니다. IDE 에서 스킬을 짤 때는 화면이 없으니, 여기서 만들고 확인은 나중에 웹에서 합니다.

온톨로지를 읽는 다섯 갈래 — 「분석해줘」는 다섯 다입니다

섹션 제목: “온톨로지를 읽는 다섯 갈래 — 「분석해줘」는 다섯 다입니다”

온톨로지 하나는 설계(노드 · 엣지)만이 아닙니다. 웹의 온톨로지 화면도 이 다섯으로 되어 있습니다. 담당자가 「분석해줘」 · 「요약해줘」 · 「현황」 · 「어디까지 왔어?」 라고 하면 다섯을 다 보고 말하십시오 — Zio.ontology(twin_id).overview() 한 번이 다섯을 모두 줍니다. 예전에 만든 스킬이 설계만 읽는다면 그 스킬을 그대로 쓰지 말고 overview() 를 부르십시오.

갈래 자세히 읽기 말할 것
목표 goal() · questions() 「가능 n / 목표 m」, 미해결이 무엇이 모자라서인지, KR 별 준비도, KPI 미연결
버전 versions() · diff() v1 → … → 현재판, 버전마다 한 줄과 바뀐 수
회의록 decisions() · decision(uuid) 회차마다 무엇을 왜 정했나, AI 제안이 있나
설계 info() 노드 · 엣지 · 속성, 경고(열쇠 없음 · source 없음)
검사 check() 외톨이 노드, 다시 판정할 질문 수

가리킨 것이 없으면 만들지 말고 묻습니다 — 모든 손잡이에 같습니다

섹션 제목: “가리킨 것이 없으면 만들지 말고 묻습니다 — 모든 손잡이에 같습니다”

담당자가 가리킨 것 — 노드 · 속성 · 관계 · 예상질문 · KR · 회의록 — 을 먼저 읽어(info() · questions() · Zio.kpi.list() · decisions()) 확인하십시오. 없거나 둘 이상이면, 찾다가 없다고 새로 만들어 처리하지 말고 묻고 멈춥니다.

  • 「A 와 B 를 잇는 관계 만들어줘」인데 둘 다 없다 → 「A · B 가 아직 없습니다. 먼저 만들까요?」(회의록에서 미룬 안건이면 그 점도 말합니다)
  • 「○○ 질문 빼줘」인데 그런 질문이 없다 → 「아직 없습니다. 새로 적고 범위 밖으로 둘까요?」
  • 「그 KR 지워줘」인데 같은 이름이 둘이다 → 둘을 보이고 어느 것인지 묻습니다.

만들라고 하면 그때 만들고, 회의록에 없는 속성 · source 를 지어내지 마십시오 — 모르면 비워 두고 무엇을 비웠는지 말합니다. 한 일은 결과에 모두 적습니다(새로 만든 것, 함께 단 회의록 · KPI · 사전 줄) — 사람이 모르는 것이 생기지 않게.

담당자가 자연어로 업무 흐름을 말하면 그것을 온톨로지로 옮기는 자리입니다. 좌표·색·내부 식별자는 SDK 가 채우니 뜻만 적으십시오.

from zio_ontology import Zio
got = Zio.ontology.create(
title="업무관리",
nodes=[
{"name": "Worklog", "title": "업무일지", "display_property": "subject",
"properties": [
{"name": "worklog_id", "title": "일지ID", "unique": True, "source": "@worklog_id"},
{"name": "subject", "title": "제목", "source": "@subject"},
]},
{"name": "Work", "title": "작업",
"properties": [
{"name": "work_name", "title": "작업명", "unique": True, "source": "@works.name"},
]},
],
edges=[{"source": "Worklog", "target": "Work", "rel": "HAS_WORK", "label": "일지의 작업"}],
)
tid = got["twin_id"]
for w in got["warnings"]:
print(w) # 오류가 안 나서 놓치기 쉬운 것들. 담당자에게 그대로 옮기십시오
Method Description
Zio.ontology.create(title, nodes, edges) 온톨로지를 새로 세우고 twin_id 를 돌려줍니다(온톨로지(TBox) 하나의 id — 버전이 바뀌어도 그대로). nodes·edges 는 안 줘도 되고, 나중에 낱개로 더해도 됩니다.
Zio.ontology.list() 온톨로지 목록. {twin_id, title, description, status, node_count, edge_count, current_version, updated_at} — current_version 은 마지막으로 남긴 버전(한 번도 안 남겼으면 None), updated_at 은 마지막으로 고친 때(웹 목록 타일과 같은 값).
↓ 여기부터는 온톨로지 하나를 집어 거는 것들입니다 — 점(.) 앞에 Zio.ontology(twin_id) 가 옵니다. list()·create() 처럼 Zio.ontology. 로 바로 부르지 않습니다. 집는 법은 아래 온톨로지대로 세우기 절을 보십시오.
Zio.ontology(twin_id).overview() 분석 · 요약할 때 먼저 — 다섯 갈래를 한 번에. {title, description, status, current_version, updated_at, design: {nodes, edges, warnings, unmapped, isolated}, versions: {current_note, list}, decisions: [{title, meeting_date, made, has_proposal}], goal: {total, target, ok, gap, todo, out, ratio, krs, by_version}, check: {to_judge, skipped}}. 「가능 n / 목표 m」은 goal.ok / goal.target 입니다.
Zio.ontology(twin_id).info() 온톨로지를 통째로 읽습니다. {twin_id, title, nodes[], edges[], warnings[]}.
.update(title, description, status) 온톨로지의 이름표를 고칩니다.
.drop() 온톨로지를 지웁니다. 이미 쌓인 Neo4j 노드(지식 그래프)는 보지도 건드리지도 않습니다 — 온톨로지는 노드를 세울 때 참고하는 종이일 뿐이라, 십만 건이 쌓였다고 종이를 못 지울 이유가 없습니다. 지우기 직전 모습은 버전 목록에 dropped-… 로 남습니다 — 아래 「버전」 상자.
.new_version(decision=None, note=None, next_note=None) 이번 회차를 버전으로 닫고 새 회차를 엽니다 — 웹 저장 창의 「새 버전으로 저장」과 같은 뜻입니다. 지금 현재판 모양이 버전 v_n 이 되고(처음이면 v1), 현재판을 만든 회의록도 그 버전으로 옮겨 갑니다. note 는 그 버전(v_n)의 한 줄입니다 — 「이번 결과로 새 버전 만들어줘, 한 줄은 ○○」이면 new_version(note="○○"). next_note 는 새로 여는 현재판의 한 줄(앞으로 할 일 — 모르면 비움), decision(쓰는 중인 회의록 uuid)은 새 현재판을 만드는 회의입니다. 부르는 때는 둘입니다. ① 반영 · 검사가 끝나 회차를 닫을 때. ② 다음 회의를 반영하기 전에 new_version(decision=새회의록) — 고치는 손잡이는 부를 때마다 바로 저장하므로, 고치기 전에 열어야 그 회의의 변경이 새 회차에 담깁니다. 마지막 버전 뒤로 고친 것이 없으면 버전을 세우지 않습니다 — decision 을 줬으면 그 회의록을 현재판에 묶고 opened: False · reason 을 돌려주며, 안 줬으면 거절합니다. {twin_id, version_tag, opened, current_version, note, decision}. 예전의 snapshot() 은 없어졌습니다(웹과 뜻이 달랐습니다).
.set_note(note, version=None) 한 줄을 고칩니다 — 웹 타임라인 제목줄의 한 줄과 같은 칸. version 을 비우면 현재판, 주면 그 버전(v1…). 설명 글 한 칸뿐이고 모양 · 바뀐 수는 그대로입니다. 빈 글이면 지웁니다. 이미 있는 줄의 한 줄을 고칠 때(오타 · 나중에 붙이기) 씁니다 — 버전을 만들며 붙이는 것은 new_version(note=…) 입니다.
.versions(limit=50, before_id=None) 버전 목록. 맨 위가 마지막으로 남긴 것입니다. {twin_id, versions: [{id, version_tag, comment, diff_summary, created_by, author_note, created_at}]} — 스냅샷 본문은 없습니다. 다음 쪽은 마지막 줄의 id 를 before_id 로 줍니다.
.version(tag) 판 하나를 통째로 읽습니다(schema_snapshot 포함). 읽기일 뿐입니다.
.diff(from_tag=None, to_tag=None) 두 버전의 뜻 차이. 한쪽을 비우면 현재판과 견줍니다. {twin_id, from, to, sizes, diff: {nodes, edges, properties, counts, …}} — sizes 는 양쪽의 전체 크기(노드 · 관계 · 속성 수, 손으로 세지 말 것), nodes·edges·properties 는 각각 added·changed·dropped 이름 목록입니다 (노드 Symptom · 엣지 Symptom-[HAS_STEP]->Step · 속성 Symptom.severity).
.record_decision(title, rationale, meeting_date=None, attendees=None, notes=None, author_note=None) 회의록 한 건을 씁니다 — 쓰는 중(아직 어느 줄에도 안 묶임). rationale(왜)이 비면 거절합니다. notes 는 회의록 원문 글 자체(마크다운)입니다 — 경로가 아닙니다. 쓰는 중인 회의록이 이미 있으면 거절합니다(하나 더 쓰지 않고 그것을 고칩니다).
.update_decision(decision, title=None, rationale=None, …, notes=None) 회의록을 준 칸만 고칩니다. 줄에 묶인 뒤에도 고칠 수 있고 버전은 그대로입니다.
.decisions(open=False, limit=50, before_id=None) 회의록 목록(최근 것부터, 원문 없음). open=True 면 쓰는 중인 것만 — 있으면 하나입니다. made 가 그 회의가 만든 줄(v1·v2…·「현재판」, 쓰는 중이면 None)입니다.
.decision(uuid) 회의록 한 건 — 원문(meeting_notes_markdown), 만든 줄(made), 그 줄이 바로 이전 버전에서 바뀐 것(target_elements).
.bind_decision(uuid, version=None) 회의록이 없는 줄에 나중에 묶습니다 — 「아차, 첫 버전 회의록을 안 남겼네」. version 이 그 버전(v1·v2…), 비면 현재판. 이미 회의록이 있는 줄은 거절합니다. 푸는 손잡이는 없습니다.
.add_node(name, title, properties=[], display_property=None) 노드를 세웁니다. display_property 는 그래프에서 원 안에 뜨는 이름이고 속성 이름 하나를 줍니다. _ 로 시작하는 이름은 다른 온톨로지의 노드를 가리키는 참조 노드로, 열쇠(PK)만 들고 세웁니다 — 아래 상자를 보십시오.
.update_node(name, title, description, display_property) 노드의 이름표를 고칩니다. name 은 못 바꿉니다 — 바꿔도 이미 그 라벨로 쌓인 노드는 안 따라옵니다(온톨로지는 지나간 데이터에 소급되지 않습니다). 이름 바꾸기 손잡이는 없습니다 — 이름만 다르게 보이면 되는 것이면 title 을 고치고, 정말로 갈아야 하면 새로 세우고 옛것을 지운 뒤 옛 라벨의 노드를 어떻게 할지는 사람이 정합니다.
.drop_node(name) 노드를 지웁니다. 붙어 있던 엣지도 함께 지우고 몇 개였는지 돌려줍니다. 남겨 두면 허공을 가리키는 엣지가 되어 웹에서 화면이 깨집니다.
.add_property(node, name, title, type, unique, required, source) 속성 한 칸을 더합니다. unique 와 source 가 무엇인지는 아래 두 상자를 꼭 읽으십시오. type 은 string · integer · float · boolean · datetime · date · time · json 중 하나이고, 안 주면 string 입니다 — 셈하거나 크기를 견줄 값(수 · 일시)은 맞는 형식을 주십시오. add_node(properties=[…]) 의 칸도 같습니다({"name", "type", "unique", …}).
.update_property(node, name, ...) 준 칸만 고치고 나머지는 그대로 둡니다.
.drop_property(node, name) 속성을 뺍니다. 그것이 display_property 였으면 그 칸도 같이 비웁니다 — 없어진 속성을 가리키는 표시명은 그래프에 빈 원으로 보입니다.
.add_edge(source, target, rel, label, source_key, target_key) 노드 둘을 잇습니다. rel 이 Neo4j 에 실제로 서는 관계 이름입니다 — add_edge("Worklog", "Author", "WRITTEN_BY") 는 그래프에 (Worklog)-[:WRITTEN_BY]->(Author) 로 섭니다. label 은 화면에만 쓰는 설명입니다. source_key·target_key 는 어느 속성끼리 맞춰 이을지 정하는 조인 키입니다(여럿이면 목록). 엣지에는 관계만 정의합니다 — 엣지에 값(속성) 칸은 없습니다.
.drop_edge(source, target, rel=None) rel 을 안 주면 그 두 노드 사이의 엣지를 모두 지웁니다.

버전 — 고친다고 저절로 남지 않습니다

섹션 제목: “버전 — 고친다고 저절로 남지 않습니다”

운영은 늘 「현재판」(온톨로지 그 자체) 하나입니다. 버전은 기록한 옛 모양 — 로그일 뿐입니다. 수집·에이전트·그래프 화면은 버전을 읽지 않습니다. 줄은 v1·v2… 그리고 맨 위의 「현재판」입니다.

온톨로지는 소스 코드가 아니라서 고칠 때마다 버전이 쌓이지 않습니다. 새 현업 미팅을 반영하기 전에 new_version(decision=…) 으로 회차를 열고, 반영 · 검사가 끝나면 new_version(note=…) 으로 그 회차를 버전으로 닫습니다. 깃의 커밋과 같습니다 — 이름(v1·v2)에는 뜻이 없고, 읽는 것은 한 줄과 회의록입니다. 웹에서 남긴 것과 SDK 로 남긴 것은 한 목록에 섭니다(웹 「버전관리」의 타임라인).

  1. 고치기 전에 엽니다. 그냥 고치면 직전 모양은 남지 않습니다 — 되돌릴 바탕은 사람이 만듭니다.
  2. 비교는 뜻만 봅니다. 좌표·색은 보지 않습니다 — 노드를 끌어 옮긴 것은 차이가 아닙니다. 엣지는 (source)-[rel]->(target) 으로 짝지으므로, rel 을 바꾼 엣지는 **「빠짐 하나 + 더함 하나」**로 나옵니다 — Neo4j 에서도 다른 관계이기 때문입니다.
  3. 과거 버전은 읽기 전용입니다. 고치는 길은 없습니다(깃처럼 이력은 보기만 합니다). 옛 모양으로 돌아가려면 웹에서 그 버전을 열어 **「이 버전으로 복원」**을 누릅니다 — 복원 전의 최신은 버전 이력에 먼저 기록되므로 이력은 앞으로만 늘고, 거꾸로 고쳐지지 않습니다. SDK 에는 복원 손잡이가 없습니다.
  4. Neo4j 는 따라오지 않습니다. 옛 판으로 돌아가도 이미 쌓인 노드는 그대로입니다(온톨로지는 소급되지 않습니다).
o = Zio.ontology(twin_id)
# 1. 고치기 전에 — 지금까지의 모양을 버전으로 닫는다 (처음이면 v1, note 는 그 버전의 한 줄)
o.new_version(note="1차 — 장애 대응 절차")
# 2. 고친다 — 고친 모양이 운영 중인 「현재판」이다
o.add_node("ProcedureStep", "작업세부단계", properties=[
{"name": "step_id", "unique": True, "source": "@step_id"}])
o.add_edge("Procedure", "ProcedureStep", "HAS_STEP")
# 3. 무엇이 바뀌었나 — 기록한 버전 ↔ 현재판
d = o.diff("v1")["diff"]
print(d["counts"]) # {'added_nodes': 1, 'added_edges': 1, ...}
print(d["nodes"]["added"]) # ['ProcedureStep']
# 이번 회차를 닫는다 — 이 모양이 v2, 한 줄은 이번에 한 일
o.new_version(note="작업세부단계 신설")

회의록 — 한 회차 = 회의록 하나 = 버전 하나

섹션 제목: “회의록 — 한 회차 = 회의록 하나 = 버전 하나”

온톨로지는 현업 미팅 → 회의록 → 설계 반영을 되풀이하며 자랍니다. 그 한 바퀴가 한 회차이고, 웹의 「버전관리」 타임라인에 한 줄로 섭니다: 그 회의가 만든 버전(v1·v2…·현재판) + 회의록(왜) + AI 제안 + 노린 KPI + 직전 버전에서 바뀐 것. 첫 버전도 그것을 만든 회의가 있을 수 있습니다 — 나중에라도 bind_decision 으로 묶습니다. 회의록도 버전처럼 로그입니다 — 운영은 읽지 않습니다.

  1. 회의록은 그 회의가 만든 줄에 묶입니다 — 줄은 「v1, v2 …, 현재판」이고 한 줄에 회의록 하나입니다.
  2. **미팅 뒤 회의록을 쓰면 「쓰는 중」**입니다(온톨로지마다 하나). 고치기 전에 new_version(decision=…) 을 부르면 현재판이 버전으로 기록되며 그것을 만든 회의록도 그 버전으로 옮겨 가고, 이 회의록이 새 현재판의 회의가 됩니다. 웹은 「새 버전으로 저장」 때 같은 일을 합니다.
  3. 회의록이 없는 줄에는 나중에 묶습니다(bind_decision, 웹은 타임라인의 「회의록 쓰기」) — 첫 버전도 됩니다.
  4. 회의록이 부족하면 하나 더 쓰지 않고 그 회의록을 고칩니다(update_decision). 버전은 그대로입니다.
  5. 지우는 손잡이는 없습니다. 회의록은 온톨로지보다 오래 사는 기록입니다 — 온톨로지를 지워도 남습니다.
o = Zio.ontology(twin_id)
# 1. 미팅이 끝나면 회의록을 쓴다 — 쓰는 중 (원문은 글 그대로, 시각은 한국 시각)
d = o.record_decision(
title="긴급 장애 대응 절차 세분화", meeting_date="2026-10-14 16:30",
attendees=["고객지원팀 김책임", "인프라팀 박선임"],
rationale="점검 없이 재기동해 2차 피해가 났다. 조치 전에 점검 스텝을 둔다.",
notes=open("meeting_20261014.md").read())
# 2. 고치기 전에 회차를 연다 — 지금 모양은 버전으로 닫히고, 이 회의록이 새 현재판의 회의
o.new_version(decision=d["uuid"])
# 3. 회의록대로 온톨로지를 고친다 — 이 회의가 만드는 새 현재판
o.add_node("ProcedureStep", "작업세부단계", properties=[
{"name": "step_id", "unique": True, "source": "@step_id"}])
# 이 회의로 바뀐 것 (마지막 버전 → 현재판)
o.decision(d["uuid"])["target_elements"]
# 빠뜨린 참석자는 그 회의록을 고친다 (버전은 그대로)
o.update_decision(d["uuid"], attendees=["고객지원팀 김책임", "인프라팀 박선임", "품질팀 이대리"])
# 첫 버전을 만든 회의를 나중에라도 남긴다
d0 = o.record_decision(title="첫 설계 인터뷰", rationale="현업 1차 인터뷰로 첫 설계를 세웠다.")
o.bind_decision(d0["uuid"], version="v1")

예상질문이 온톨로지의 목표입니다. 현업이 데이터에 묻고 싶은 것을 그 말 그대로 적고, 이 설계로 답이 되는지를 판정합니다. 「가능 n / 목표 m」이 웹 「목표」 화면의 띠이고, 버전이 거듭될수록 n 이 늘어야 합니다. 질문은 KPI(KR) 에 연결됩니다 — KPI 는 온톨로지가 아니라 인스턴스의 것이라 Zio.kpi 에 있습니다(아래 표).

  1. 사람이 정하는 것 — 질문 글 · 연결된 KPI · 나온 회의록 · 범위 밖(이 온톨로지가 답할 질문이 아님).
  2. AI 가 채우는 것 — 판정(가능 · 미해결) · 근거 · 답하는 경로 · 해결 Cypher · 닿는 노드(judge). 한 판 안에서 다시 검사하면 덮어씁니다(컴파일 결과처럼).
  3. 상태 값 — todo 미검토 · ok 가능 · gap 미해결 · out 범위 밖. 범위 밖은 목표 수(분모)에서 빠지고, AI 가 판정하지 않습니다 — 사람이 말했을 때만 정하고 풉니다. 담당자에게 말할 때는 화면 이름 그대로(미검토 · 가능 · 미해결 · 범위 밖) 씁니다 — 「모자람」 같은 다른 말로 바꾸지 않습니다. 질문과 KR 사이도 화면 말 그대로 「연결」(연결된 KPI · KPI 미연결)이라고 씁니다.
  4. 질문 글을 고치면 판정이 비워집니다 — 다른 질문이 된 것입니다.
  5. KPI 는 맞는 것만 잇습니다. 질문 하나에 KR 은 대개 하나입니다 — 둘 이상 이을 때는 까닭을 말하십시오. 이름이 닮았다고 잇지 마십시오. 기간 · 단위가 다른 KR 은 같은 지표가 아닙니다(하루 ↔ 월, 건 ↔ %) — 「한 달에 몇 건」 질문을 「하루 처리 건수」 KR 에 잇지 않습니다. 맞는 것이 없으면 비워 두십시오(「KPI 미연결」은 정리할 거리로 보입니다).
  6. 가리킨 질문 · KR 이 없거나 둘 이상이면 묻습니다 — 맨 앞 「가리킨 것이 없으면 만들지 말고 묻습니다」 상자.
  7. 노린 KPI(target_kpis)는 시켰을 때만 겁니다 — 사람이 「이번 회차는 ○○을 노린다」고 말했을 때입니다. 질문을 KR 에 이었다고 회의록에 노린 KPI 를 저절로 걸지 마십시오.
  8. 버전을 넘기면 「현재판에서 판정」이 「v2 에서 판정」처럼 굳고, check() 가 그 질문들을 다시 판정할 것으로 짚습니다.
Method (온톨로지 — Zio.ontology(twin_id)) Description
.questions(status=None, touches=None, kr=None) 예상질문 목록 — [{id, question, judgment: {status, basis, path, checked_version, decision_uuid}, kr_uuids, cypher_query, touches}]. touches="Part" 면 그 노드에 닿는 질문만(「Part 를 지우면 어느 질문이 영향받나」), kr="-" 면 KPI 미연결만.
.add_question(question, kr=None, decision=None) 질문 하나 — 미검토로 섭니다. kr 은 연결된 KR uuid(하나 또는 목록, Zio.kpi.list() 에서), decision 은 나온 회의록. 맞는 KR 이 없으면 억지로 잇지 마십시오(「KPI 미연결」로 보입니다). 같은 글은 거절합니다.
.update_question(id, question=None, kr=None, decision=None) 준 칸만 고칩니다. kr 은 그 목록 그대로 맞춥니다([] 면 모두 끊음), decision="" 면 회의록을 비웁니다.
.exclude_question(id, reason) · .include_question(id) 범위 밖으로 정하고 · 풉니다(풀면 미검토). 지우지 않습니다 — 「왜 안 하느냐」의 근거로 남습니다. reason 이 비면 거절합니다. 「빼줘」가 범위 밖인지 삭제인지 가려 들으십시오.
.drop_question(id) 질문을 지웁니다(KPI 연결도 함께).
.goal(by_version=False) {total, target, ok, gap, todo, out, ratio, unlinked, krs: [{kr_uuid, name, objective, ok, target}]} — 웹 목표 화면의 띠 · KR 카드와 같은 숫자. by_version=True 면 by_version: [{version, saves, goal_counts}](「버전별 달성」 그래프의 점, 기록 전의 판은 None, 「현재판」은 늘 지금 판정 수, saves 는 그 판을 만들며 저장한 횟수 — 함께 말하십시오).
.check() 검사의 첫 걸음 — {nodes, edges, warnings, unmapped, isolated, to_judge, skipped}. unmapped 는 매핑 전 노드 유형(경고 아님). isolated 는 엣지에 안 닿는 노드, to_judge 는 판정할 질문(미검토 · 이전 판에서 판정한 것), skipped 는 범위 밖.
.judge(id, status, basis, path=None, cypher=None, touches=None) AI 의 판정 — status 는 "ok" 또는 "gap" 만, basis(근거)가 비면 거절합니다. ok 면 어느 경로로 답하나와 해결 Cypher(이 온톨로지의 라벨 · 관계 그대로), gap 이면 무엇이 모자라나를 적습니다. 범위 밖 질문은 거절합니다. 근거 없는 ok 는 쓰지 마십시오. 돌려주는 값의 cypher_warnings 는 Cypher · touches 에 쓴 라벨 · 관계 유형 · 속성 가운데 온톨로지에 없는 것입니다 — 비어 있지 않으면 그 판정은 근거가 없는 것이니 Cypher 를 고쳐 다시 판정하거나, 정말 모자라면 "gap" 으로 판정하십시오.
.propose(decision, markdown) 그 회의록의 AI 제안을 씁니다 — 통째로 바꿉니다(다시 제안하면 덮어쓰기). 웹은 보기만 합니다. 제안은 글이고 캔버스에 얹는 것은 add_node 등으로 따로 합니다. 회의록 원문은 건드리지 않습니다. 절(약속): ## 요약 · ## 노드 · 속성 제안(근거 칸) · ## 연결 제안 · ## 예상질문과의 관계 · ## 열린 질문 · ## 동의어 사전에 올릴 말. 회의록 하나에 제안 하나이고 통째로 덮어씁니다 — 같은 회의록에 다른 이야기(예: 미해결 보완안)를 남기려면 앞 절을 그대로 두고 새 절을 덧붙여 다시 쓰십시오. 「제안해줘」만 들었으면 대화로 답하고, 기록은 「기록해줘」를 들었을 때 합니다. 「제안대로 반영해줘」는 노드 · 속성 · 관계만 고치는 일입니다 — 「동의어 사전에 올릴 말」을 사전에 넣는 것(Zio.glossary.add)과 노린 KPI(target_kpis)는 사람이 그렇게 하라고 할 때 따로 합니다. 함께 했다면 결과에 적으십시오.
.target_kpis(decision, kr) 그 회차(회의록)가 노린 KPI — 웹 버전관리의 「노린 KPI」. 그 목록 그대로 맞춥니다([] 면 모두 끊음). 돌려주는 added · removed 에 더하고 뺀 것이 옵니다 — removed 가 있으면 있던 것이 빠진 것이니 결과에 적으십시오.update_question(kr=…) 도 같은 뜻의 kr_changes 를 돌려줍니다.
t = Zio.ontology(twin_id)
kr = Zio.kpi.list()[0]["results"][0]["uuid"] # 연결할 KR — 인스턴스의 KPI 에서 고른다
q = t.add_question("지난달 처리가 늦어진 건은 몇 건이고, 무엇 때문인가?", kr=kr, decision=d["uuid"])
t.exclude_question(q2_id, reason="외부 시스템이 맡는 일(2차 회의)") # 사람이 「범위 밖」이라 했을 때만
# 검사 — 구조 점검을 보고, 판정할 질문마다 그래프로 답하는 길을 짚는다
c = t.check()
print(c["warnings"], c["isolated"])
for x in c["to_judge"]:
t.judge(x["id"], "gap", basis="Part 에 재주문 기준 수량이 없습니다", touches=["Part"])
t.goal() # {'total': 12, 'target': 11, 'ok': 7, ...} — 웹 목표 화면의 「7/11」
Method (인스턴스 — Zio.kpi · Zio.glossary) Description
Zio.kpi.list() O 마다 KR — [{uuid, title, results: [{uuid, name, unit, current, target, direction, improvement}]}]. 수치는 현업과 합의한 문서입니다 — 현행 · 목표만 있고 실적 칸은 없습니다. 같은 O 를 또 만들지 않도록 먼저 봅니다.
Zio.kpi.links(kr=None) 그 KR 에 연결된 것 — 어느 온톨로지의 어느 질문(판정 포함) · 어느 회차가 노리나. 비면 인스턴스 전체.
Zio.kpi.add_objective(title) · update_objective(o, title) · drop_objective(o) 목표(O). 돌려받은 dict 를 그대로 넘겨도 됩니다. KR 이 남은 O 는 지우지 않습니다. add_objective · add_result 는 돌려주는 값에 similar (이름이 비슷한 O · KR, [{uuid, name, objective, score}])를 붙입니다 — 막지 않습니다. 비어 있지 않으면 사람에게 「이미 있는 ○○과 같은 것인가」를 물으십시오 (「재고조사 실행시간」 ↔ 「재고 조사 실행 시간」). 같으면 방금 만든 것을 지우고 있던 것을 씁니다.
Zio.kpi.add_result(o, name, current, target, unit=None, direction="down") KR(지표) — 「재고조사 실행시간 12시간 → 2시간」. direction 은 "down"(낮을수록 좋음) · "up"(높을수록 좋음) — 말에서 알아들으십시오(줄이는 → down, 늘리는 → up). 개선율은 서버가 셉니다 — 음수면 방향을 틀리게 둔 것입니다.
Zio.kpi.update_result(kr, name=, current=, target=, unit=, direction=, objective=) · drop_result(kr) 준 칸만 고칩니다. KR 을 지우면 연결돼 있던 질문은 남고 「KPI 미연결」이 됩니다.
Zio.glossary.list(q=None) 동의어 사전 — {entries: [{uuid, name, aliases, meaning}], more}. 설계 전에 읽으십시오 — 노드 이름은 사전명을 따릅니다.
Zio.glossary.add(name, aliases=None, meaning=None) 사전에 올립니다. 사전명은 대소문자를 가리지 않고 하나 — 이미 있으면 새 줄 없이 동의어만 붙입니다(merged: True). added_aliases 가 비어 있으면 바뀐 것이 없습니다 — 「이미 사전에 있다」고 말하고, 「반영했다」고 하지 마십시오. 뜻을 바꾸는 것은 update(meaning=…) 이고, 돌려주는 meaning_before(전의 뜻)를 함께 알리십시오.
Zio.glossary.update(name, new_name=, aliases=, remove_aliases=, meaning=) · drop(name) 사전명(또는 uuid)으로 고치고 · 지웁니다. aliases 는 더하기만 합니다(있던 동의어는 그대로) — 빼려면 remove_aliases=["말", …] 로 이름을 대십시오. 남이 넣은 동의어를 말없이 지우지 않게, 지우기는 따로 시킵니다. 돌려주는 added_aliases · removed_aliases 를 결과에 적으십시오. 이미 있는 말을 「넣어줘」는 add 하나로 끝납니다(merged: True).
o = Zio.kpi.add_objective("현황 파악을 하루 단위에서 실시간으로")
Zio.kpi.add_result(o, "월말 집계 소요 시간", current=12, target=2, unit="시간", direction="down") # 개선율 83%
Zio.glossary.add("Supplier", aliases=["공급처", "거래처"], meaning="물품을 대 주는 곳")

언더바(_) — 다른 온톨로지의 노드를 가리키는 지름길

섹션 제목: “언더바(_) — 다른 온톨로지의 노드를 가리키는 지름길”

온톨로지를 그리다 다른 온톨로지 안에 이미 있는 노드(예: 공용 Author·Project)에 이어야 할 때, 그 노드를 여기서 다시 정의하지 않고 이름 앞에 _ 를 붙여 가리킵니다. 화면에서 「이 노드가 저기 있는 노드와 이어진다」를 보여 주는 온톨로지 위의 표기입니다. 두 규칙만 지키면 됩니다.

  1. 노드 이름 앞에 _ 를 붙입니다. (_Author, _Project)
  2. 속성은 열쇠(PK)만 적습니다. 가리키는 데 필요한 건 짝을 맞출 열쇠뿐이라, 나머지 칸은 의미가 없습니다 — 읽기 좋으라고 열쇠 한둘만 남깁니다.

언제 _ 를 쓰나 — 이 온톨로지가 그 노드의 값을 (수집으로) 채우는 주인이면 일반 노드로, 이미 다른 온톨로지가 채우고 있고 당신은 잇기만 하면 될 때 _ 로. 「다른 온톨로지에 있는지 먼저 찾아볼」 필요는 없습니다 — 같은 이름이 같은 노드라는 보장이 없고, 판단 기준은 존재 여부가 아니라 **「내가 채울 주인인가」**입니다.

**「온톨로지에서는 만들 수 있고, Neo4j 에는 서지 않는다」**가 핵심입니다. 저장할 때 _ 는 벗겨져 같은 라벨의 그 노드로 MERGE 됩니다(_Project → 그래프의 Project) — 재정의가 아니라 가리키기라, 열쇠만 들고 와 잇기만 하고 그 노드의 제목·소속·표시명은 덮어쓰지 않습니다. 그래서 실제 insert/update 때 _ 붙은 노드가 새로 생기는 일은 없습니다.

Zio.ontology.create(title="WBS", nodes=[
{"name": "Worklog", "properties": [
{"name": "worklog_id", "unique": True, "source": "@id"}]},
{"name": "_Project", "properties": [ # 다른 온톨로지 노드 참조 (열쇠만)
{"name": "project_code", "unique": True, "source": "@project_code"}]},
], edges=[{"source": "Worklog", "target": "_Project", "rel": "BELONGS_TO"}])

add_node·create 로 SDK 에서 바로 만들 수 있습니다 — 웹으로 되돌아가 고칠 필요가 없습니다. 참조 노드의 열쇠에 source 를 주면 수집 데이터가 그 값을 채워 자동으로 이어지고, 값을 직접 넘길 땐 아래 .save() 에서 _Project 에 열쇠만 실어 보냅니다.

unique — 같은 노드인지 가르는 열쇠

섹션 제목: “unique — 같은 노드인지 가르는 열쇠”

속성 중 가장 중요한 칸입니다. 이것으로 「이미 있는 그 노드」인지 「새 노드」인지를 가릅니다.

unique 개수 무슨 일이 일어나나
0 개 실행할 때마다 노드가 새로 쌓입니다(MERGE 가 아니라 CREATE). 오류가 안 나서 몇 주 뒤에야 압니다.
1 개 그 값으로 MERGE. 있으면 두고 없으면 만듭니다.
2 개 이상 값을 _ 로 이어 열쇠로 씁니다. 한 칸이라도 비면 그 건은 통째로 안 섭니다.

정한 열쇠의 값이 비면 그 건만 건너뜁니다 — 열쇠 없는 유령 노드를 막는 것입니다.

안 주면 그 속성은 늘 비어 있습니다. 오류는 안 나고 그 칸만 빠진 채 노드가 섭니다.

적는 것 뜻
@issues.title 수집 데이터의 issues 안의 title
@worklog_id 수집 데이터의 worklog_id
그냥 글자 적어 둔 글자가 곧 값 (상수)

@ 뒤 경로의 앞부분이 배열이면 원소마다 노드가 하나씩 섭니다 — @issues.title 에서 issues 가 셋이면 노드도 셋입니다. 배열을 노드 여럿으로 펴는 유일한 방법입니다.

경로는 실제 수집 데이터의 칸을 알 때만 적습니다.Zio.ingestion.schemas() 의 columns(필요하면 Zio.ingestion(이름).fetch() 로 레코드 하나)를 보고 고르십시오. 회의를 반영하는 설계 단계처럼 아직 수집 데이터가 없으면 비워 둡니다 — 그런 노드 유형은 info() · check() · overview() 의 unmapped(매핑 전) 에 모입니다. 경고가 아닙니다 — 설계 단계에서는 정상이고, 매핑할 때 채울 목록입니다. 경고를 없애려고 @customer_name 같은 경로를 지어내지 마십시오 — 경고는 사라지지만 실제로는 값이 하나도 안 들어오는데, 이번에는 아무도 그것을 알아채지 못합니다.

노드 속성은 시스템 필드와 한 자리에 평평하게 담깁니다. 그래서 겹치면 시스템 쪽이 이기고, 오류 없이 조용히 어긋납니다. SDK 가 미리 막습니다.

이름 겹치면
id · source · target · labels 그래프가 식별자로 씁니다. 연결선이 안 그려집니다
title · twin_id 저장할 때 시스템이 덮어씁니다
x·y·z·vx·vy·vz·fx·fy·fz·index·color 그래프 화면이 덮어씁니다
_ 로 시작하는 것 시스템 예약입니다(_display)
name 막지는 않지만, 쓰면 자동 표시명이 그 값으로 고정됩니다

온톨로지를 손에 쥐고 그리는 대로 세웁니다. 노드도 엣지도 온톨로지가 압니다. 스킬은 값만 넘깁니다 — 어느 엣지를 어느 방향으로 걸지는 한 줄도 쓰지 않습니다.

Zio.node().merge() 는 노드 하나를 세웁니다. 엣지는 merge_relation() 으로 직접 걸어야 합니다. 노드가 둘 셋으로 늘고 트리까지 있으면, 산업별 담당자가 온톨로지를 그려 놓고도 같은 그림을 파이썬으로 또 그리게 됩니다. 그 자리를 이 묶음이 대신합니다.

Method Description
Zio.ontology(twin_id, entry_node=None) 온톨로지 하나를 집습니다. twin_id 는 온톨로지(TBox) 하나의 id 이고, 노드에 twin_id 속성으로 그대로 박히는 값입니다. entry_node 는 뿌리 노드 이름으로, 쓰기에만 필요합니다.
.save(data) 온톨로지에 그려진 대로 노드와 엣지를 세웁니다. data 는 {노드이름: [인스턴스, …]} 입니다.

두 인자는 에이전트의 「온톨로지 노드 연결」과 같은 것입니다. 에이전트 빌더에서 온톨로지와 진입 노드를 고르는 그 두 칸이 여기서는 인자가 됩니다.

# 에이전트가 부르는 모양 (수집 경로 — 값을 온톨로지의 @경로가 끌어온다)
execute_ontology_entry("lAOZtMeH", "Worklog", state)
# 스킬이 부르는 모양 (값을 직접 준다)
Zio.ontology("tNpBkLim", "WbsItem").save({
"WbsItem": [
{"project_code": "PRJ-0071", "item_name": "GS25 8월 정기점검",
"status": "진행중", "progress_pct": 62,
"parent_item_name": "GS25 정기점검 3Q"},
{"project_code": "PRJ-0071", "item_name": "GS25 정기점검 3Q",
"status": "진행중"},
],
"_Project": [{"project_code": "PRJ-0071"}],
"_Work": [{"worklog_id": "weekly_sjlee1_2026_32", "work_name": "8월 정기점검"}],
})

이 한 번으로 WbsItem 두 개가 서고, REPORT_ON · BELONGS_TO · HAS_SUBTASK 가 함께 걸립니다. 엣지 이야기는 코드에 없습니다.

자리 규칙
노드 이름 온톨로지에 적힌 그대로 씁니다. 언더바 접두도 그대로입니다 (_Project). 라벨은 SDK 가 벗겨 냅니다 — 그래프에는 Project 로 들어갑니다. 온톨로지에 없는 이름은 조용히 무시됩니다.
인스턴스 목록이면 원소 하나가 노드 하나입니다. 낱개 dict 도 받습니다. 속성 이름은 온톨로지의 속성명입니다.
안 넣는 것 name · _display · title · twin_id 는 SDK 가 붙입니다. 넣으면 계산된 값을 밀어냅니다.

엣지는 이번에 넘긴 노드끼리만 걸립니다. 온톨로지에 그려져 있어도 한쪽을 안 넘기면 그 엣지는 안 섭니다.

# _Project 를 안 넘기면
Zio.ontology("tNpBkLim", "WbsItem").save({"WbsItem": [...]})
# → WbsItem 은 선다
# → WbsItem -[BELONGS_TO]-> Project 는 안 선다
# 열쇠만 넘기면 붙는다
"_Project": [{"project_code": "PRJ-0071"}]

그래서 언더바 접두 노드는 열쇠만 넘깁니다. 이미 있는 노드를 찾아 붙이는 것이 목적이고, 속성은 그 노드를 만든 온톨로지가 채웁니다. 열쇠만 넘기면 그 노드의 속성은 하나도 안 바뀝니다.

자기 자신을 가리키는 엣지는 온톨로지가 짝을 짓습니다

섹션 제목: “자기 자신을 가리키는 엣지는 온톨로지가 짝을 짓습니다”

WBS 트리나 선행 작업처럼 같은 노드끼리 잇는 엣지는 온톨로지의 「키 매핑」이 짝을 정합니다. 스킬은 부모 이름을 속성으로 적어 두기만 하면 됩니다.

엣지 sourceKey targetKey
HAS_SUBTASK project_code, item_name project_code, parent_item_name
PRECEDES project_code, item_name project_code, previous_item_name

가리키는 부모가 아직 없으면 이름만 든 껍데기로 세웁니다. 나중에 그 부모의 값이 들어오면 채워집니다. 트리가 끊기는 것보다 낫다고 보았습니다.

{
"written": True, # 썼는가
"saved": {"WbsItem": 2, "_Project": 1, "_Work": 1}, # 실제로 세운 수
"skipped": [
{"node": "WbsItem", "index": 3, "reason": "열쇠가 비었습니다"},
],
"message": "Data saved successfully to Neo4j.",
}

saved 는 넘긴 수가 아니라 선 수입니다. 둘이 다르면 skipped 를 보십시오.

written 은 “썼는가” 이지 “성공했는가” 가 아닙니다. 뿌리 열쇠가 비어 아무것도 안 쓴 것은 실패가 아니라 판단입니다 — 값이 안 온 것뿐이고, 그때는 되묻기를 걸 자리입니다.

규칙 왜
전부 되거나 전부 안 된다 노드와 엣지를 다 만든 뒤 한 번에 실행합니다. 도중에 어긋나면 그래프에는 아무것도 안 쓰입니다. 반쯤 선 그래프가 없습니다.
열쇠가 비면 안 세운다 아무도 못 찾는 노드가 생기지 않게 합니다. 그 인스턴스만 건너뛰고 나머지는 그대로 섭니다.
두 번 돌려도 같다 열쇠로 찾아 없으면 만들고 있으면 갱신합니다. 같은 값을 다시 넘겨도 노드가 늘지 않습니다.
넘긴 칸만 갱신한다 이미 있는 노드에는 이번에 값을 준 칸만 씁니다. 온톨로지를 고쳐도 지나간 노드를 다시 쓰지 않습니다.
Zio.node().merge() Zio.ontology().save()
세우는 것 노드 하나 온톨로지에 그려진 노드와 엣지
엣지 merge_relation() 으로 직접 온톨로지가 안다
온톨로지 안 본다 본다
쓸 때 속성 한 칸 고치기 · 되묻기 반영 추론이 만든 것을 통째로 세우기

뿌리가 없으면 아무것도 안 씁니다

섹션 제목: “뿌리가 없으면 아무것도 안 씁니다”

entry_node 로 준 노드가 이번 데이터의 뿌리입니다. 그 노드의 열쇠가 비어 있으면 저장을 통째로 중단합니다 — 뿌리 없이 가지만 남으면 나중에 아무도 그것을 찾아가지 못합니다. 위 예에서 WbsItem 을 뿌리로 준 이유가 이것입니다.

(주)지오유 · 경기 용인시 처인구 유림로154번길(유방동 673-2) 20-13

대표자 신달수·사업자등록번호 142-81-36612·통신판매업 신고번호 용인처인-0118호·개인정보 관리책임자 신달수·전자우편 shindalsoo@gmail.com·전화 1833-3623·팩스 02-6918-4006