semantica-agi/semantica · 라이선스 MIT(Copyright 2026 Hawksight AI) · 백엔드 Python 3.8+ / FastAPI(:8000) · 프런트 React 19 + Sigma.js + Vite 6 · 패키지 파일 약 616개·약 174K LOC · 버전 v0.6.0 · ★ 1,887·fork 259 · 최신 push 2026-08-05 · 저자 Kaif Ahmad(@KaifAhmad1) · getsemantica.ai · TrendShift Daily #21)
Semantica는 "당신의 LLM·벡터DB·에이전트 스택 아래에 깔려서, 데이터를 지식 그래프로 만들고 · AI가 내린 모든 결정을 출처와 인과 사슬까지 기록해 · 나중에 규제기관이 '왜 그랬냐'고 물으면 그대로 재현·감사할 수 있게 만드는 결정론적 인프라 계층"이다. 한마디로 "AI 판단의 비행기록장치(FDR·블랙박스 레코더)"다. 스스로 답을 내는 AI가 아니라, AI가 낸 답의 근거·경로·책임 소재를 남기는 기록·설명 계층이다.
비행기에는 블랙박스(비행기록장치)가 있다. 조종사가 어떤 순간에 어떤 계기값을 보고 어떤 조작을 했는지, 그 판단들이 어떻게 연쇄됐는지를 전부 기록한다. 사고가 나면 조사관은 이 기록을 되감아 "어느 판단이, 어떤 데이터를 보고, 무엇 때문에 내려졌는지"를 한 치의 상상 없이 복원한다.
Semantica가 정확히 이 블랙박스 역할이다. 당신의 AI 에이전트가 대출을 거절하거나 진단을 제안할 때, Semantica는 그 결정(decision)을 근거 노드에 연결하고, 앞선 결정과 인과로 잇고(CAUSED·INFLUENCED·PRECEDENT_FOR), W3C PROV-O 출처를 붙여 그래프에 남긴다. 그래서 나중에 trace_decision_chain() 한 번이면 "이 판단에 이른 전체 사슬"이 규제기관 제출용 감사 리포트로 튀어나온다. LLM처럼 그럴듯하게 지어내는 게 아니라, 결정론적으로 기록된 사실만 되감는다.
record_decision()으로 남긴 뒤 인과로 이어, trace_decision_chain·analyze_decision_impact·check_decision_rules로 질의·검증·규정 게이트를 통과시킨다. 결과는 규제기관이 바로 읽을 수 있는 PROV-O / CSV / JSON 감사 추적으로 내보낼 수 있다.사용자(에이전트)가 "이 대출 신청을 어떻게 처리했지?"라고 되물을 때 Semantica 안에서 벌어지는 일을 압축하면 이렇다:
여기서 핵심은 ①·②·③이 전부 결정론적이라는 점이다. 그래프 구축도, 추론도, 출처 기록도 LLM을 부르지 않고 코드로 돌아간다(LLM은 선택적으로만 얹힌다). 그래서 같은 입력엔 같은 그래프·같은 감사 결과가 나온다 — "재현 가능성"이 규제 대응의 생명인 영역에서 이 "LLM 없는 결정론"이 Semantica 설계 철학의 뼈대다.
첫째, RAG와 에이전트 메모리가 못 하는 "결정·인과·출처"를 정면으로 채운다. README의 자체 비교표가 차별점을 그대로 요약한다:
| 항목 | 벡터DB + RAG | LLM 메모리 | Semantica |
|---|---|---|---|
| 회상(recall) | 임베딩 유사도 | 토큰 윈도우 | 그래프 순회 + 의미 검색 |
| 결정 이력 | 저장 안 함 | 저장 안 함 | 질의 가능한 1급 객체 |
| 출처(provenance) | 없음 | 없음 | W3C PROV-O, 소스 링크 |
| 추론 | 없음 | 블랙박스 | Rete·Datalog·SPARQL(설명 가능) |
| 충돌 처리 | 조용히 덮어씀 | 조용히 덮어씀 | 탐지·표시·해소 |
| 시간 여행 | 불가 | 불가 | 시점 스냅샷(bi-temporal) |
| 규정 export | 없음 | 없음 | PROV-O·SHACL·OWL·RDF |
둘째, "그래프 네이티브"가 마케팅이 아니라 실제 저장·연산 방식이다. 사실·관계·결정이 진짜 그래프에 살아, 타입·가중치 엣지와 BFS 순회, bi-temporal 사실, 중심성·커뮤니티·링크 예측 분석이 붙는다. 게다가 저장소가 다형(polyglot)이다 — RDF 트리플스토어(Blazegraph·Apache Jena·Eclipse RDF4J를 SPARQL로)와 라벨 속성 그래프(Neo4j·FalkorDB·Apache AGE·AWS Neptune을 Cypher로)를 코드 수정 없이 교체할 수 있다.
회계 장부 vs 영수증 상자. 그냥 영수증을 상자에 던져 넣으면(=벡터DB에 임베딩만 쌓으면) 나중에 "이 돈이 왜 나갔지?"를 복원할 수 없다. 반면 복식부기 장부는 모든 거래를 차변·대변으로 잇고 근거 전표를 붙여, 감사관이 어떤 항목이든 근원까지 역추적할 수 있다. Semantica는 AI의 판단을 "영수증 상자"가 아니라 "복식부기 장부"로 남기는 쪽이다 — 모든 결정이 근거·인과·출처로 묶여, 사후에 통째로 되감긴다.
셋째, Neo4j·GraphRAG·Zep·Mem0과 결이 다르다. 순수 그래프DB(Neo4j)와 달리 수집→추출→중복제거→추론→출처→결정으로 이어지는 전체 파이프라인을 갖췄고, 에이전트 메모리 제품(Zep·Mem0)과 달리 결정 + 인과 사슬 + 출처 + 거버넌스(SHACL·OWL·정책 규칙)까지 저장한다. 게다가 벤더 종속 없이 자체 호스팅이 되고, 추론·KG·출처 계층이 전부 결정론적이라 LLM이 필요 없다. 기존 스택을 버리라는 게 아니라 그 위에 "책임성 계층"을 얹으라는 상보적 포지셔닝이다.
넷째, 기업 데이터 플랫폼과 바로 물린다. DatabricksIngestor(Unity Catalog + Delta Lake, PAT/OAuth M2M, 리니지 조회)와 SnowflakeIngestor가 내장돼, 웨어하우스 테이블을 제3자 SaaS로 내보내지 않고 곧장 거버넌스 그래프 노드로 바꾼다. "데이터를 밖으로 못 보내는" 규제 조직에게 이 로컬·자체호스팅 성질은 결정적이다.
대부분의 "설명 가능한 AI"는 사후에 그럴듯한 설명을 생성한다(그 설명 자체가 또 블랙박스다). Semantica는 반대다 — 결정을 내리는 그 순간에 근거 노드·인과 엣지·출처를 그래프에 기록해 두고, 나중엔 그걸 되감을 뿐이다. 설명을 지어내지 않고 기록을 재생하므로, 규제·감사 맥락에서 신뢰할 수 있는 결정론적 추적이 된다. "생성된 설명"과 "기록된 추적"의 차이가 이 프로젝트의 핵심 가치다.
README의 "The Open Source Palantir"·"6,000배 빠름" 같은 표현은 열정적 마케팅에 가깝다. "6,000배" 수치는 자동 테스트가 검증하는 값이 아니라 CHANGELOG의 과거 측정치이고, ReteEngine의 알파-노드 조건 매칭은 README 스스로 "이번 릴리스에서는 의도적으로 단순 — 운영 규정 게이트에 물리기 전 검증하라"고 밝힌다. Python >=3.8 선언도 numpy>=2.0.2를 감안하면 낙관적이다. 다만 코드 폭·테스트 미러·CI·문서는 실제로 방대하고 진지하다 — 과장된 카피 뒤에 견고한 엔지니어링이 있는, 흔치 않은 조합이다.
Semantica는 Python 코어 패키지(수집·그래프·추론·출처·결정)에 React 19 프런트(Explorer)가 얹힌 구조다. 특이하게 기본 의존성만으로도 이미 무겁다 — torch·transformers·spacy·faiss가 기본에 들어가고, 실제 백엔드/그래프/벡터 연동은 extras(선택 의존)로 잘게 쪼개 필요한 것만 깔게 했다.
| 영역 | 라이브러리 | 역할 |
|---|---|---|
| 과학·수치 | numpy>=2.0.2 · pandas · scipy · scikit-learn · umap-learn · gensim | 임베딩·차원축소·군집 등 그래프 분석의 수치 토대 |
| NLP·ML | spacy>=3.4 · transformers>=4.20 · torch>=1.13 · sentence-transformers · tokenizers | NER·관계추출·이벤트 탐지·임베딩(엔티티/관계 추출 엔진) |
| 그래프·RDF | rdflib>=6.2 · networkx>=2.8 | RDF 트리플 모델 + 인메모리 그래프 알고리즘 |
| 벡터·임베딩 | faiss-cpu · fastembed · onnxruntime | 하이브리드 검색(벡터 유사도)의 기본 백엔드 |
| 문서 파싱 | beautifulsoup4 · lxml · pypdf2 · python-docx · openpyxl · pillow · librosa · opencv-python | PDF·워드·엑셀·이미지·오디오까지 다형 소스 인제스트 |
| 인프라·CLI | pydantic>=2 · click>=8.4 · rich · httpx · loguru · structlog · grpcio · protobuf | 스키마 검증 · 86개 CLI 명령 · 로깅 · 통신 |
pip install "semantica[...]"llm-openai/anthropic/gemini/groq/ollama/deepseek/litellm), 그래프 백엔드(graph-neo4j/falkordb/amazon-neptune/apache-age), 벡터스토어(vectorstore-qdrant/weaviate/pinecone/milvus/pgvector/sqlite), DB(db-snowflake/databricks/arrow), 큐(redis·celery·kafka·pulsar), 클라우드(boto3·azure·gcs), 모니터링(prometheus·opentelemetry)까지 전부 extras다. 필요한 조합만 골라 까는 "조립식 인프라"인 셈.| 구성요소 | 기술 | 역할 |
|---|---|---|
| 본체 | React 19.2 + TypeScript 5.9 | 지식 탐색 워크벤치(11개 워크스페이스: Graph·Decision·Ontology·Reasoning·Sparql·Lineage…) |
| 그래프 시각화 | sigma.js v3 + graphology | 대규모 그래프 렌더링 + ForceAtlas2 레이아웃·Louvain 커뮤니티·최단경로·중심성 |
| 노드 편집 | @xyflow/react(React Flow 12) | 온톨로지·규칙을 노드-엣지로 시각 편집 |
| 코드 에디터 | @monaco-editor/react | SPARQL/코드 인라인 편집 |
| 타임라인 | vis-timeline · vis-data | bi-temporal 시점 스크러버(시간 여행 UI) |
| 빌드 | Vite 6 + babel-plugin-react-compiler | React Compiler 적용 · 빌드 산출물은 semantica/static/에 동봉 |
semantica/explorer/app.py) — WebSocket 지원, 11개 라우트 모듈(analytics·decisions·graph·ontology·provenance·sparql·temporal…)에 약 80개 라우트 데코레이터. README는 "100+ 엔드포인트"라 표기.node:26-alpine이 프런트를 빌드하고, python:3.14-slim 런타임이 .[explorer]를 설치해 uvicorn semantica.explorer.app:app을 :8000에서 구동. 비루트 유저 + /api/health 헬스체크.deploy/) — Helm 차트(deployment·service·ingress·hpa·networkpolicy) + 원시 k8s 매니페스트 + Azure(bicep)·Fly.io·GCP(Cloud Run)·Railway·Render..checkov.yaml(Checkov+Terrascan IaC 스캔) · .pre-commit-config.yaml · GitHub Actions(ci·codeql·security-scan·defender-for-devops·benchmark·release·docs) · Dependabot.pip install semantica 한 방이 수 GB ML 스택을 끌고 온다기본 의존에 torch·transformers·spacy·faiss·opencv·librosa가 들어 있어, 아무 옵션 없이 설치해도 멀티 GB 다운로드 + 상당한 RAM이 필요하다. "가벼운 그래프 라이브러리"를 기대하고 깔면 놀란다. 또 pyproject.toml은 >=3.8이라 적었지만 numpy>=2.0.2는 사실상 3.9+를 요구한다 — CI는 3.11, 도커 런타임은 3.14를 쓰니 실전에선 3.11+를 권한다. 일부 인제스터(DuckDB·Elastic·GDrive·HF·Mongo·Pandas)는 아직 최상위 네임스페이스로 재노출되지 않아 직접 import해야 한다.
파이프라인의 모든 단계가 독립적으로 import 가능한 모듈이다. 소스에서 서빙까지를 한 그림으로 하면:
핵심 성질 셋. (1) 수집·구축·추론·출처가 전부 결정론적이다 — LLM은 필수가 아니라 선택. (2) 저장소가 갈아끼워진다 — RDF(트리플)든 LPG(속성 그래프)든 벡터든, 같은 인터페이스 뒤에서 백엔드만 바꾼다. (3) 서빙 표면이 넷이다 — 사람이 쓰는 CLI/웹, 에이전트가 쓰는 REST/MCP가 같은 그래프 하나를 공유한다.
| 단계 / 모듈 | 핵심 클래스 | 하는 일 |
|---|---|---|
semantica.ingest | FileIngestor · WebIngestor · DatabricksIngestor · SnowflakeIngestor · ArrowIngestor | 다형 소스 → 원시 문서 |
semantica.semantic_extract | NamedEntityRecognizer · RelationExtractor · EventDetector · TripletExtractor · CoreferenceResolver | 텍스트 → 엔티티·관계·이벤트·트리플 |
semantica.conflicts | ConflictDetector · ConflictResolver · SourceTracker | 모순 탐지 + 신뢰도·최신·투표 전략으로 해소 |
semantica.kg | GraphBuilder · EntityResolver · CentralityCalculator · CommunityDetector · LinkPredictor · BiTemporalFact · TemporalGraphQuery | 지식 그래프 구축 + 분석 + 시간 여행 |
semantica.reasoning | ReteEngine · DatalogReasoner · SPARQLReasoner · ExplanationGenerator · Rule · Fact | 규칙 추론 + 설명 가능한 트레이스 |
semantica.provenance | ProvenanceManager | 사실마다 W3C PROV-O 출처 부여 |
semantica.context | ContextGraph · AgentContext · DecisionRecorder · CausalChainAnalyzer · PolicyEngine | 맥락 그래프 + 결정 기록·인과·정책 게이트 |
semantica.pipeline · .core | PipelineBuilder · ExecutionEngine · plugin_registry · orchestrator | 선언적 병렬 DAG 오케스트레이션 + 플러그인 레지스트리 |
콘솔 엔트리포인트도 이 모듈들과 1:1로 붙는다(pyproject.toml [project.scripts]): semantica(CLI) · semantica-server(REST) · semantica-worker · semantica-explorer · semantica-mcp.
이 프로젝트의 정체성을 가장 잘 보여 주는 대목이다. 일반 스택은 결정을 로그 한 줄로 흘려보내지만, Semantica는 결정을 그래프 노드로 남기고 인과로 잇는다. 개념 코드는 이렇다(escape된 </> 주의):
# 결정을 1급 객체로 기록하고, 나중에 통째로 되감는다
ctx = ContextGraph()
decision = ctx.record_decision(
action="대출 신청 거절",
rationale="신용점수 620, 임계값 650 미만", # '620 < 650' 를 근거로
inputs=[credit_report_node, income_node], # 근거 노드에 실제로 연결
)
ctx.link_decision(decision, cause=prior_review, rel="PRECEDENT_FOR")
# --- 나중에, 규제기관이 "왜 거절했나" 물으면 ---
chain = ctx.trace_decision_chain(decision) # 이 판단에 이른 전체 인과 사슬
similar= ctx.find_similar_decisions(decision) # 과거 유사 판례
ok = ctx.check_decision_rules(decision) # 정책 게이트(SHACL/규칙) 통과?
ctx.export_provenance(decision, fmt="prov-o") # 규제 제출용 감사 추적CAUSED·INFLUENCED·PRECEDENT_FOR로 인과 연결) → ③ Query(사슬 추적·유사 판례·영향 분석) → ④ Govern(check_decision_rules로 정책 게이트 통과 검사) → ⑤ Audit(PROV-O/CSV/JSON로 감사 추적 export). "결정을 데이터로 다룬다"는 발상이 핵심이다.Semantica가 규모 있는 인프라로 보이는 이유가 여기 있다. 같은 그래프를 세 종류 저장소에 담을 수 있고, 코드는 그대로다:
semantica.triplet_store) — Blazegraph · Apache Jena · Eclipse RDF4J를 SPARQL로. 표준 온톨로지·추론에 강함.semantica.graph_store) — Neo4j · FalkorDB · Apache AGE · AWS Neptune을 Cypher로. 운영·성능에 강함.semantica.vector_store, HybridSearch) — faiss·Qdrant·Weaviate·Milvus·pgvector·sqlite-vec를 RRF 융합으로. 의미 검색 담당.(주어, 술어, 목적어) 트리플로 표현하고 SPARQL로 질의한다 — 표준·온톨로지·추론(OWL/SHACL)에 강하다. LPG는 노드·엣지에 속성(property)을 직접 달고 Cypher로 질의한다 — 직관적이고 운영·성능에 강하다. Semantica는 둘을 어댑터로 추상화해, 온톨로지가 필요하면 RDF로·운영 속도가 필요하면 LPG로 같은 데이터를 갈아끼운다.TemporalGraphQuery가 이걸로 "A가 B보다 먼저였나·겹쳤나"를 정확히 판정한다.Semantica는 에이전트에게 MCP(Model Context Protocol) 도구로 그래프를 내준다. 표면이 둘이다: (1) semantica/mcp_server/__init__.py — 표준 라이브러리만으로 된 단일 파일 stdio JSON-RPC 서버(semantica-mcp), 12개 도구(extract_entities · record_decision · query_decisions · find_precedents · get_causal_chain · run_reasoning · get_graph_analytics · export_graph 등)를 노출. (2) 최상위 mcp/ — 도구를 decisions/export/extraction/graph/reasoning.py로 쪼갠 모듈형 재구현.
여기에 .claude/skills/semantica/SKILL.md가 있어, Claude Code가 "언제 KG/결정/추론/출처 워크플로를 써야 하는지"를 스킬로 학습한다. plugins/에는 Cursor·Codex·Windsurf·Cline·Continue·VS Code용 플러그인 번들과 17개 도메인 스킬(extract·ingest·query·reason·decision·causal·temporal·provenance·policy·explain…), 3개 에이전트(kg-assistant·decision-advisor·explainability)가 함께 들어 있다.
CLI(86 명령)·Explorer(웹)는 사람이, REST(100+)·MCP(12 도구)는 에이전트가 쓴다. 그런데 이 넷이 전부 같은 semantica.context·semantica.kg 코어를 호출한다 — 표면만 다르고 알맹이는 하나다. "핵심 로직은 한 번만 쓰고, 표면(surface)을 여러 개 얇게 얹는다"는 이 구조는 라이브러리 + 서비스 + 에이전트 도구를 동시에 제공해야 하는 요즘 인프라 설계의 좋은 표본이다.
구조가 알려주는 힌트 셋. 첫째, 가장 큰 파일이 cli.py(4,246줄)와 context_graph.py(3,432줄)다 — 무게중심이 "화려한 UI"가 아니라 "결정·맥락 그래프의 코어 로직"과 "그걸 다 노출하는 86개 CLI 명령"에 실려 있다. 둘째, vector_store/graph_store/triplet_store가 나란히 있는 것 자체가 "다형 저장소"가 사후 땜질이 아니라 설계의 축임을 보여 준다. 셋째, tests/가 27개 모듈을 통째로 미러링한다 — 모듈마다 대응 테스트가 있다는 건 리팩터링·기여를 받쳐 주는 진지한 엔지니어링 신호다.
Ingest·Parse·Normalize·Split·Extract·Conflict·Dedup·KG·Reasoning·Provenance·Context가 각각 한 디렉토리로 갈려 있어, 데이터가 흐르는 순서를 폴더 이름만 훑어도 재구성할 수 있다. "어디를 고쳐야 하지?"를 파일 탐색이 아니라 파이프라인 단계로 사고하게 만드는 구조 — 큰 데이터 시스템을 모듈로 쪼개는 법을 배우기에 훌륭한 표본이다.
요즘 대부분은 LLM을 맨 위에 올린다. Semantica는 반대로 그래프·추론·출처를 LLM 없이 결정론적으로 깔고, LLM은 선택적으로만 얹는다. "재현 가능성·감사 가능성이 필요한 부분은 코드로, 창의성이 필요한 부분만 LLM으로" 나누는 이 경계 설계는 규제·기업 환경에서 AI를 쓰는 법의 핵심이다. 어떤 AI 시스템이든 "어디까지가 결정론이어야 하는가"를 고민할 때 참고가 된다.
RDF·LPG·벡터라는 세 저장 패러다임을 하나의 인터페이스 뒤에 숨기고 백엔드만 갈아끼우는 설계. graph_store·triplet_store·vector_store의 어댑터 코드를 읽으면 "공급자 종속 없이 저장소를 추상화하는 법"을 실물로 배운다. 이건 데이터베이스뿐 아니라 결제·메시징·클라우드 등 "여러 벤더를 하나의 API로 받는" 모든 상황에 이식되는 패턴이다.
로그가 아니라 그래프 노드·엣지로 결정과 근거를 남기고, W3C PROV-O 같은 표준으로 내보내는 방식. "설명을 사후에 생성"하는 대신 "기록을 재생"하는 발상의 전환이 핵심이다. 감사·컴플라이언스가 필요한 어떤 시스템(금융·의료·보안 로그)에도 그대로 응용할 수 있다.
LLM 시대에도 여전히 강력한 고전 추론 엔진들을 실물로 볼 기회다. ReteEngine(규칙 매칭 네트워크)·DatalogReasoner(재귀 질의)·SPARQLReasoner가 각각 설명 가능한 트레이스를 남기는 구조를 뜯어 보면, "왜 이 결론이 나왔는가"를 형식적으로 증명하는 법을 배운다. 신경망이 못 주는 결정론적 설명 가능성의 세계다.
"지금의 그래프"가 아니라 "과거 임의 시점의 그래프"를 되감는 양시간 모델링과 Allen 구간 대수. kg/temporal_query.py(1,758줄)를 읽으면 "데이터가 언제 참이었나 vs 언제 기록됐나"를 분리해 저장·질의하는 실전 기법을 얻는다. 이력 추적·감사·규제 보고가 필요한 시스템의 필수 지식이다.
같은 코어를 CLI·REST·MCP로 동시에 노출하고, .claude/skills/·plugins/로 여러 코딩 에이전트에 붙이는 방식. "내 도구를 에이전트가 자율적으로 호출하게 만드는" 요즘의 통합 패턴을 실전 규모로 볼 수 있다. MCP 서버를 직접 짜 보려는 사람에게 좋은 레퍼런스다.
거창한 KG 없이도 핵심 발상은 체험할 수 있다. 아무 스크립트에서 어떤 판단(예: "이 사용자를 차단")을 내릴 때, 그냥 print로 로그를 남기는 버전과 — 판단·근거·이전 판단을 작은 딕셔너리 그래프({id, action, rationale, inputs, caused_by})로 남기는 버전을 둘 다 만들어 보라. 그리고 "3번 판단은 왜 나왔지?"를 근거 사슬을 따라 되감아 출력해 보면, Semantica의 trace_decision_chain이 왜 로그보다 강력한지 곧바로 체감된다.
| 항목 | 필요한 것 |
|---|---|
| 런타임 | Python 3.8+(선언) — 실전 권장 3.11+(numpy>=2.0.2, CI=3.11, 도커=3.14). Explorer 빌드엔 Node.js |
| 설치 용량·RAM | 기본 의존에 torch·transformers·spacy·faiss·opencv·librosa 포함 → 멀티 GB 다운로드 + 상당한 RAM. 가벼운 그래프 툴이 아님 |
| GPU | 선택(semantica[gpu] → faiss-gpu·cupy, 리눅스). 전 기능이 CPU만으로 동작 |
| 외부 서비스 | 전부 선택·교체형 — 그래프DB(Neo4j/FalkorDB/Apache AGE/Neptune) · RDF 트리플스토어(Blazegraph/Jena/RDF4J) · 벡터스토어(Qdrant/Pinecone/Milvus/pgvector/sqlite-vec) · 큐(Redis/Celery/Kafka/Pulsar). 도커 기본 백엔드=FalkorDB |
| LLM | 선택 — 그래프·추론·출처는 LLM 없이 동작. 필요 시 extras로 OpenAI/Anthropic/Gemini/Groq/Ollama/DeepSeek 등 연결 |
| 목적 | 명령 |
|---|---|
| 기본 설치·점검 | pip install semantica → semantica doctor(파이썬·버전·faiss·~/.semantica/config.yaml 헬스체크) |
| REST API | python -m semantica.server (:8000) |
| MCP 서버 | python -m semantica.mcp_server 또는 semantica-mcp (stdio JSON-RPC, 12 도구) |
| Explorer(웹) | pip install "semantica[explorer]" → semantica-explorer --graph my_graph.json (127.0.0.1:8000, Node 불필요) |
| 운영 배포 | Docker / docker-compose(+FalkorDB) / Helm / k8s. SEMANTICA_SECRET_KEY 설정 |
doctor로 점검하기 ★ 초급 30분pip install semantica 후 semantica doctor를 돌려 Python 버전·faiss·설정 파일(~/.semantica/config.yaml)이 전부 pass인지 확인한다. 기본 설치가 torch·transformers를 끌고 와 멀티 GB라는 점을 몸으로 체감하는 것도 이 과제의 일부다 — 가상환경(venv) 하나를 전용으로 파서 진행하라.
README Quick Start 그대로 — 결정 하나를 노드로 남기고, 4가지 질의로 되감는다:
from semantica.context import ContextGraph
graph = ContextGraph(advanced_analytics=True)
decision_id = graph.record_decision(
category="vendor_selection",
scenario="Choose cloud provider for HIPAA workload",
reasoning="AWS offers BAA, mature HIPAA tooling, ...",
outcome="selected_aws", confidence=0.93,
)
chain = graph.trace_decision_chain(decision_id) # 전체 인과 사슬
similar = graph.find_similar_decisions("cloud vendor", max_results=5)
impact = graph.analyze_decision_impact(decision_id) # 하류 영향 지도
compliant = graph.check_decision_rules({"category": "vendor_selection"})README의 대표 레시피(약물 상호작용 사례)를 재현한다: 결정 두 개를 기록하고 add_causal_relationship(d1, d2, relationship_type="CAUSED")로 인과를 잇고, ProvenanceManager.track_entity()로 출처를 붙인 뒤 RDFExporter().export(..., format="turtle")로 W3C PROV-O 감사 추적을 뽑는다. 함정 하나 — RDFExporter는 {"entities", "relationships"} 형태를 기대하므로 ContextGraph.to_dict()의 {"nodes", "edges"}를 매핑해서 넘겨야 한다(README에 매핑 코드가 그대로 있다).
문서 폴더 하나로 5단계를 관통한다: FileIngestor().ingest_directory() 수집 → TextSplitter(method="entity_aware")로 엔티티를 경계에서 안 자르는 청킹 → NamedEntityRecognizer·RelationExtractor 추출 → GraphBuilder(merge_entities=True)로 KG 구축 → HybridSearch로 "who approved the renewal?" 같은 질문에 벡터+그래프 하이브리드 검색. cookbook의 intro 노트북들이 같은 흐름을 단계별로 안내한다.
README의 More Recipes에 있는 ReteEngine 제재국 거래 탐지 룰(amount > 10_000 AND country in ["IR","KP","SY","CU"] → flag_for_compliance_review)을 만들고 Fact 배치를 흘려 match_patterns()로 걸러 본다. 이어서 pip install "semantica[explorer]" → semantica-explorer --graph my_graph.json으로 워크벤치(:8000)를 띄워 Decisions·Lineage 워크스페이스에서 인과 사슬을 눈으로 확인한다. 단, README 스스로 경고하듯 Rete의 조건 매칭은 아직 단순하니 운영 규정 게이트에 물리기 전 자기 룰셋으로 검증할 것.
| 요일 | 학습 내용 | 실습 |
|---|---|---|
| 월 | 지식 그래프 vs 벡터DB vs LLM 메모리 | README 비교표 정독 + §2의 7항목 차이 정리 |
| 화 | RDF 트리플 · SPARQL 기초 | rdflib로 트리플 만들고 질의해 보기 |
| 수 | LPG(속성 그래프) · Cypher 기초 | docker-compose로 FalkorDB 띄우기 |
| 목 | 설치·환경 구성 | pip install semantica → semantica doctor |
| 금 | 전체 파이프라인 조감 | cookbook intro 노트북(21개 중 앞부분) 따라 하기 |
| 요일 | 학습 내용 | 실습 |
|---|---|---|
| 월 | 다형 소스 인제스트 | FileIngestor로 문서 디렉토리 수집 |
| 화 | KG 인지 청킹 | TextSplitter의 entity/relation-aware 방식 비교 |
| 수 | 엔티티·관계·이벤트 추출 | NamedEntityRecognizer·RelationExtractor 실행 |
| 목 | KG 구축 + 그래프 분석 | GraphBuilder → 중심성·커뮤니티 탐지 |
| 금 | 충돌·중복 처리 | ConflictDetector·중복 병합 전략 실험 |
| 요일 | 학습 내용 | 실습 |
|---|---|---|
| 월 | Rete 규칙 매칭 | ReteEngine으로 규칙 하나 작동시키기 |
| 화 | Datalog · SPARQL 추론 | DatalogReasoner 재귀 질의 실습 |
| 수 | W3C PROV-O 출처 | ProvenanceManager + RDFExporter로 turtle export |
| 목 | 결정 지능 5단계(Record→Audit) | record_decision → trace_decision_chain |
| 금 | bi-temporal · 시간 여행 | TemporalGraphQuery로 과거 시점 스냅샷 질의 |
| 요일 | 학습 내용 | 실습 |
|---|---|---|
| 월 | REST API 표면 | python -m semantica.server → curl로 추출·결정 질의 |
| 화 | MCP로 에이전트에 꽂기 | semantica-mcp(12 도구)를 Claude Code에 연결 |
| 수 | Explorer 워크벤치 | Graph·Decisions·Ontology·Lineage 워크스페이스 탐방 |
| 목 | 배포 | Docker / docker-compose(+FalkorDB) / Helm 차트 읽기 |
| 금 | 종합 프로젝트 | 자기 데이터로 "수집→KG→결정 기록→PROV-O export" 완주 |
| 키워드 | 설명 |
|---|---|
| 그래프 네이티브 | 표·벡터가 아니라 그래프(노드+엣지)를 1차 시민으로 저장·연산하는 방식. Semantica의 정체성 |
| 지식 그래프 (KG) | 엔티티·관계·이벤트를 노드와 타입·가중치 엣지로 담은 그래프. semantica.kg가 구축·분석 |
| 맥락 그래프 | ContextGraph — 에이전트의 결정·근거·인과를 담는 그래프. 결정 지능의 저장소 |
| 결정 지능 | 결정을 1급 객체로 Record→Link→Query→Govern→Audit 하는 5단계 라이프사이클 |
| W3C PROV-O | 출처(provenance)를 기술하는 W3C 표준 온톨로지. 규제 제출용 감사 추적의 export 포맷 |
| 출처 (provenance) | "이 사실이 어디서 왔는가"의 기록. 모든 사실·결정에 원본 소스 링크가 붙는다 |
| RDF 트리플스토어 | 사실을 (주어, 술어, 목적어) 트리플로 저장 — Blazegraph·Jena·RDF4J를 SPARQL로 질의 |
| SPARQL | RDF 그래프 질의 언어. Semantica에선 추론(SPARQLReasoner)에도 쓰인다 |
| LPG · Cypher | 라벨 속성 그래프와 그 질의 언어 — Neo4j·FalkorDB·Apache AGE·Neptune 계열 |
| Rete | 다수 규칙을 효율적으로 매칭하는 고전 알고리즘. ReteEngine의 기반 |
| Datalog | 재귀 질의가 가능한 논리형 질의 언어. "bob의 모든 조상" 같은 질의에 강함 |
| OWL · SHACL · SKOS | 온톨로지 정의(OWL)·그래프 형상 검증(SHACL)·어휘 체계(SKOS)의 W3C 3종 표준 |
| bi-temporal | "실제로 참이었던 때"와 "시스템이 기록한 때"를 분리 저장 — 시간 여행 질의의 토대 |
| Allen 구간 대수 | 두 시간 구간의 관계를 13가지로 형식화한 이론. TemporalGraphQuery가 사용 |
| GraphRAG | 벡터 유사도에 그래프 순회를 결합한 검색-증강 생성. entity-aware 청킹이 짝을 이룸 |
| 하이브리드 검색 | HybridSearch — 벡터 유사도 + 그래프/키워드를 RRF 융합으로 합산하는 검색 |
| 인과 관계 타입 | 결정을 잇는 세 엣지 — CAUSED·INFLUENCED·PRECEDENT_FOR |
| MCP | Model Context Protocol — 에이전트에게 도구를 내주는 표준. semantica-mcp가 12 도구 노출 |
| extras | pip install "semantica[...]"로 백엔드·LLM·큐를 골라 까는 선택 의존성 체계 |