semantica-agi/semantica — Graph-Native Infrastructure for Context and Accountable AI Systems

한 줄 요약

semantica-agi/semantica는 문서·웹·DB·스트림에서 지식을 추출해 지식 그래프, 벡터/그래프 저장소, ontology, reasoning, provenance, 에이전트 메모리와 결정 감사 로그로 연결하는 Python 프레임워크다.[1][4][5] 저장소가 내세우는 핵심 방향은 단순 RAG 라이브러리보다 AI 시스템의 컨텍스트와 결정 과정을 그래프-native·감사 가능 구조로 만드는 것에 가깝다.[6]

조사 기준과 저장소 현황

조사 기준은 이동하는 main이 아니라 6f310d1d7acf11013dc7e68d4e68823eb96cec4d 고정 커밋이다.[2]
고정 커밋의 제목은 docs: link CONTRIBUTING.md issue workflow from PR template (#896)이고, 작성자는 Mohd Kaif, 시각은 2026-08-10T21:18:01+05:30이다.[2]
패키지 버전은 0.6.0이며 v0.6.0 릴리스는 2026-07-21에 게시되었다.[5][25]
고정 HEAD는 v0.6.0 이후의 main 스냅샷이므로, 릴리스 버전과 최신 개발 브랜치의 문서·코드 상태를 구분해서 읽어야 한다.[2][25]

2026-08-18 재검증

GitHub API: 별 ~5,600개(3,979→약 1.4배), fork 618개(476→약 1.3배), 마지막 push 2026-08-18T13:24:52Z.[30]
v0.6.5 릴리스(2026-08-11)는 보안 릴리스다. 주요 수정:[31]
- Critical: Explorer API 11개 라우터 전부 인증 미비(누구나 그래프 read/write + SPARQL 실행 가능) → Depends(require_auth) + SEMANTICA_API_KEY 검증 추가, 기본 fail-closed.[31]
- Critical: Cypher injection 경로 수정.[31]
- High: ontology URL fetching의 SSRF 리다이렉트 우회 + DNS check-then-use hardening.[31]
- CodeQL ReDoS 수정.[31]
- 내장 Oxigraph TripletStore 백엔드 추가, Altair Anzo triplet store 백엔드 추가.[31]
- ProvenanceManager PROV-O trust/spec 완전성 보장.[31]
- 벡터 저장소, provenance, ontology 검증, Explorer 프론트엔드 전반에 걸쳐 25+ 정확성 버그 수정.[31]
v0.6.5는 모든 배포에 업그레이드가 강력히 권장된다特别是 Explorer API를 사용하는 경우.[31]
GitHub API 조회 시 저장소는 Python/MIT/비아카이브 상태이며 별 약 5,600개, fork 618개, open issue 53개로 나타났다.[3]
조사·raw 캡처 시각은 2026-08-11 05:31 KST다. raw 캡처에는 고정 커밋, 원문 파일 목록, provenance와 본문 SHA-256을 함께 기록했다.

무엇을 제공하는가

Semantica 문서는 27개 독립 import 가능 모듈을 여섯 계층으로 나눈다.[7]

계층	모듈	역할
Input	`ingest`, `parse`, `split`, `normalize`	파일·웹·DB·스트림을 읽고 파싱·정규화·분할
Core Processing	`semantic_extract`, `kg`, `ontology`, `reasoning`	엔터티·관계 추출, KG 구성, schema/ontology, 추론
Storage	`embeddings`, `vector_store`, `graph_store`, `triplet_store`	임베딩·벡터·그래프·RDF triple 저장
Quality Assurance	`deduplication`, `conflicts`	중복 엔터티와 소스 간 충돌 처리
Context & Memory	`context`, `provenance`, `change_management`	에이전트 메모리·결정·계보·버전 관리
Output & Orchestration	`export`, `visualization`, `pipeline`, `explorer`	내보내기·시각화·워크플로·Knowledge Explorer

저장소가 제시하는 전체 흐름은 Ingest → Parse → Normalize → Split → Extract → Conflict/Dedup → KG Construction → Ontology/Reasoning/Provenance/Context → Storage → Export/Visualization/Services다.[6][7]

핵심 데이터 흐름

1. 입력·추출

FileIngestor, WebIngestor, DBIngestor, ParquetIngestor, XMLIngestor, RepoIngestor, EmailIngestor, MCPIngestor 등은 서로 다른 입력을 공통 문서 흐름으로 합친다.[6][7] 파서 계층은 PDF·DOCX·PPTX·HTML·CSV·JSON·Excel·XML과 코드·웹·이메일 형식을 다루며, 분할기는 recursive·semantic·entity-aware·relation-aware·structural 전략을 제공한다.[7]

semantic_extract는 NER, relation extraction, triplet extraction, event detection, coreference와 semantic analysis를 묶는다.[7][17] 추출 방식은 API 키가 필요 없는 pattern, 로컬 모델을 쓰는 ML, 외부 LLM provider를 쓰는 LLM 방식으로 나뉜다고 문서화되어 있다.[7]

2. 지식 그래프 구성

GraphBuilder는 엔터티와 관계를 그래프 노드·엣지로 조립하고, merge_entities=True 같은 설정으로 중복 엔터티 병합을 파이프라인 안에 배치한다.[7][18] KG 계층에는 중심성·community detection·connectivity·path finding·link prediction·similarity·temporal graph query가 포함된다.[7]

그래프는 ontology, reasoning, provenance, context/decision 계층의 공통 기반이 된다.[6] 따라서 이 프로젝트의 차별점은 “추출 결과를 검색 인덱스에만 넣는 것”보다, 엔터티·관계·시간·출처·결정·추론을 같은 지식 구조에서 이어 붙이는 것이다.[6][7]

3. 저장과 출력

벡터 저장소는 FAISS·Pinecone·Weaviate·Qdrant·Milvus·PgVector·in-memory backend와 semantic/hybrid/metadata-filtered 검색을 문서화한다.[5][7] 그래프 저장소는 Neo4j·FalkorDB·Apache AGE·Amazon Neptune, RDF triple 저장소는 Blazegraph·Jena·RDF4J·Anzo·Oxigraph 계열을 노출한다.[7]

출력 계층은 Turtle·JSON-LD·N-Triples·RDF/XML·OWL·SHACL·Parquet·CSV·GraphML·Cypher·ArangoDB AQL 등으로 내보내고, KG·ontology·embedding·temporal 시각화와 FastAPI Knowledge Explorer를 제공한다.[6][7]

에이전트 컨텍스트와 메모리

ContextGraph는 노드와 엣지에 속성·시간 유효 구간을 담는 thread-safe in-memory property graph다.[9] 구현은 Python dictionary/list와 threading.RLock을 사용하며, BFS 이웃 탐색·temporal snapshot·저장/로드·FAISS 기반 semantic search와 연결될 수 있다.[14]

AgentContext는 vector store와 knowledge graph를 조정해 관찰·문서·대화 내용을 저장하고, semantic score와 graph proximity를 섞어 관련 컨텍스트를 검색하는 상위 인터페이스다.[8][15] conversation_id, user_id, metadata, retention, max memories, graph expansion, hybrid alpha 같은 필드로 세션·사용자·보존 정책과 retrieval 방식을 분리한다.[8]

이 설계는 단순 vector RAG와 달리 “비슷한 문장”뿐 아니라 특정 엔터티에서 몇 hop 떨어져 있는지, 어떤 관계로 연결되는지를 검색 점수에 반영하려는 접근이다.[8][9] 다만 기본 ContextGraph는 외부 DB가 아닌 메모리 구조이므로, 재시작을 넘는 보존에는 명시적 save/load나 영속 backend 구성이 필요하다.[9]

Provenance와 audit trail

ProvenanceManager는 엔터티·관계·문서 chunk·property value의 출처와 변환 이력을 W3C PROV-O 형태로 기록한다고 문서화되어 있다.[10] 각 레코드에는 source document, source location/quote, confidence, activity, operator와 SHA-256 checksum을 둘 수 있고, 같은 엔터티를 다시 추적하면 version chain을 만든다.[16]

저장 backend는 zero-dependency in-memory와 SQLite를 제공하며, SQLite 쪽은 WAL·busy timeout·atomic update를 사용하도록 구현되어 있다.[10][16] SourceReference는 문서·section·위치·confidence·사용자 metadata를 묶어 “이 property 값이 어디서 왔는가”를 추적하는 세밀한 연결점이다.[29]

이 계층은 지식 그래프의 설명 가능성을 단순한 생성 모델의 rationale 저장보다 넓게 본다. 데이터가 어느 source에서 왔고, 어떤 변환을 거쳤으며, 이전 버전과 무엇이 달라졌는지를 audit trail로 남기는 구조다.[10][16]

Decision Intelligence

Semantica는 에이전트의 결정을 일회성 응답이 아니라 graph node로 저장한다.[11] 결정에는 category, scenario, reasoning, outcome, confidence, timestamp, decision maker, entity links와 temporal metadata가 들어가며, 이후 similarity 기반 precedent search에 사용될 수 있다.[26]

CausalAnalyzer는 결정 간 CAUSED, INFLUENCED 같은 관계를 upstream/downstream으로 따라가며, 초기 분류가 escalation·containment·patch priority 같은 후속 행동에 어떻게 이어졌는지 추적한다.[11][27] PolicyEngine은 정책을 graph node로 저장하고 결정의 confidence·reasoning·category 등을 검사한 뒤 policy application과 예외 승인 기록을 남기는 경로를 제공한다.[28]

따라서 Decision Intelligence의 실무적 모델은 record → causal link → precedent/query → policy gate → audit export다.[6][11] 이는 Agent Memory가 외부 지식·관찰을 저장하는 것과 달리, 에이전트 자신이 내린 분류·승인·행동을 내부 의사결정 데이터로 저장하는 구분도 분명히 한다.[11]

Reasoning과 ontology

Reasoning 계층은 retrieval이나 traversal이 이미 저장된 사실을 찾는 데 그치는 것과 달리, 규칙을 적용해 원문에 직접 적히지 않은 결론을 도출하는 역할을 맡는다.[12] 문서에는 forward/backward chaining, Datalog, SPARQL, RETE, temporal reasoning, LLM-backed graph reasoning, explanation generation이 별도 모드로 정리되어 있다.[12]

Datalog는 recursive Horn clause와 semi-naive fixpoint로 arbitrary-depth 관계를 다루고, ContextGraph의 노드·엣지를 facts로 변환해 reasoning working memory를 만들 수 있다.[12] 파생 사실은 같은 세션의 working memory에 먼저 들어가며, graph에 영속화하려면 별도 저장 경로가 필요하다고 문서에 적혀 있다.[12]

Ontology 계층은 SHACL·SKOS·OWL·namespace·alignment·diff/migration·auto-generation과 Ontology Hub를 제공하는 것으로 설명된다.[7] 즉, Semantica는 “그래프를 만든다”에서 멈추지 않고, 그래프의 의미 제약과 inferred facts를 관리하려는 방향을 갖는다.[6][7]

MCP·REST·CLI 실행면

MCP server는 stdio subprocess로 실행되며 Claude Desktop, Windsurf, Cline, Continue, VS Code 등 MCP client에서 사용할 수 있다.[13] 고정 커밋의 MCP 구현은 12개 tool과 3개 read-only resource를 선언한다.[19]

주요 tool은 extract_entities, extract_relations, record_decision, query_decisions, find_precedents, get_causal_chain, add_entity, add_relationship, run_reasoning, get_graph_analytics, export_graph, get_graph_summary다.[19] SEMANTICA_KG_PATH를 지정하면 로컬 graph 파일을 로드할 수 있고, 지정하지 않으면 프로세스 수명 동안의 빈 in-memory graph로 시작한다.[13]

MCP 문서는 이 server가 REST API나 원격 HTTP service가 아니며, client가 로컬 subprocess를 실행하고 stdio로 통신한다고 명시한다.[13] 따라서 MCP 사용자는 local file permission과 graph file 경로를 신뢰 경계로 봐야 하고, 원격 multi-tenant service로 오해해서는 안 된다.[13][19]

별도 semantica-server entry point는 FastAPI/uvicorn REST surface와 Knowledge Explorer route를 제공한다.[5][20] 현재 snapshot의 /build handler는 실제 build_knowledge_base 호출이 주석 처리된 채 accepted 응답을 반환하므로, 이 endpoint는 완성된 비동기 build queue라기보다 placeholder/scaffold로 판단하는 것이 안전하다.[20]

패키징과 운영 보안

pyproject.toml은 Python >=3.8과 MIT를 선언하고, core dependency에 NumPy·Pandas·SciPy·scikit-learn·spaCy·Transformers·Torch·Sentence Transformers·FAISS·RDFLib·NetworkX·FastAPI 주변 의존성을 폭넓게 포함한다.[5] 기능별 optional extra는 LLM provider, Docling, SHACL, Snowflake/Databricks/Arrow, graph/vector backend, monitoring, explorer, dev 도구 등으로 나뉜다.[5]

이 구조는 모듈별 기능 선택을 가능하게 하지만, “독립적으로 import 가능하고 사용하지 않는 기능은 비용을 내지 않는다”는 문서 메시지와 달리 기본 설치 자체는 상당히 무겁다는 trade-off가 있다.[5][7] 최소 설치·경량 실행을 목표로 한다면 core dependency 정책과 직접 import되지 않는 optional backend를 구분해 배포해야 한다.[5]

CI workflow는 Explorer frontend를 npm으로 테스트·build하고 Python wheel을 만든 뒤 static asset이 wheel에 포함되는지 확인한다.[21] release workflow는 tag push를 기준으로 build, Explorer asset 검증, build provenance attestation, GitHub Release와 PyPI publish 경로를 구성하며 OIDC/id-token과 attestation 권한을 별도 job에 둔다.[23]

Security Scan workflow는 Safety·Bandit·Semgrep을 실행하고, Safety report 부재나 dependency vulnerability, Bandit HIGH severity는 실패 조건으로 검사하지만 Semgrep 결과는 informational로 처리한다.[22] SECURITY.md는 Actions SHA pinning, Trusted Publishing, branch protection, secret scanning, CodeQL·pip-audit·Dependabot 등의 통제를 저장소 보안 posture로 설명하지만, 이 문서는 프로젝트가 선언한 정책이며 이 조사에서 각 repository setting을 독립 검증한 것은 아니다.[24]

이번 조사에서 수행한 검증

고정 clone의 작업 트리는 clean이며 main이 조사 커밋 6f310d1을 가리켰다.
python3 -m compileall -q semantica는 성공했다.
import semantica는 성공했고 __version__은 0.6.0이었다.
pytest는 현재 실행 환경에 설치되어 있지 않아 테스트 스위트를 실행하지 못했다.
ContextGraph·ProvenanceManager·Reasoner 기능 스모크 테스트는 import 단계에서 numpy가 없어 실행되지 않았다.
따라서 로컬 검증 결과는 컴파일과 최상위 import 성공으로 한정하며, 전체 테스트·기능 실행·성능·보안 스캔 성공으로 확대 해석하지 않는다.

평가: 어디에 맞는가

강점

문서 ingest부터 graph construction, provenance, decision audit, reasoning, export까지 하나의 Python 패키지 안에서 연결된다.[6][7]
vector similarity와 graph proximity를 함께 사용해 장기 에이전트의 context retrieval을 구조화한다.[8][9]
결정·정책·causal chain을 graph object로 만들기 때문에 설명 가능성과 precedent search를 제품 기능으로 다룰 수 있다.[11][28]
MCP stdio, FastAPI Explorer/REST, CLI, 다양한 storage/export backend를 제공해 같은 graph를 여러 실행면에 노출한다.[5][13][20]

트레이드오프와 주의점

core dependency가 무겁고 ML/embedding/FAISS 계층을 기본 dependency로 포함하므로 가벼운 문서 파서나 단순 MCP만 필요한 경우 설치 비용이 크다.[5]
기본 ContextGraph는 in-memory이므로 persistence, backup, concurrent multi-process write를 별도 설계해야 한다.[9][14]
reasoning의 파생 사실과 AgentContext의 저장 상태는 자동으로 모든 external backend에 영속화되는 것이 아니며, 저장 경계를 운영자가 명시해야 한다.[8][12]
/build REST endpoint처럼 문서상 표면과 실제 구현 성숙도가 다른 곳이 있으므로, 도입 전 endpoint별 integration test가 필요하다.[20]
README와 SECURITY.md의 성능·보안·배포 설명은 프로젝트의 자기 기술이다. 0.004ms 같은 Explorer 수치나 “regulator-ready” 표현을 외부 벤치마크·감사 결과로 읽어서는 안 된다.[4][24]

결론

Semantica는 “문서를 LLM에 넣는 RAG 유틸리티”보다 지식을 그래프로 축적하고, 에이전트의 기억·추론·결정·출처를 하나의 감사 가능한 context layer로 운영하려는 프레임워크로 보는 편이 정확하다.[6] 특히 보안 분석·연구·compliance·decision support처럼 관계·시간·근거·결정 이력이 중요한 도메인에서 설계 방향이 잘 맞는다.[8][10][11]

반대로 단일 문서 검색, 가벼운 embedding prototype, 외부 서비스가 이미 persistence와 policy를 담당하는 단순 agent에는 전체 패키지와 그래프 계층이 과할 수 있다.[5][9] 도입한다면 먼저 ContextGraph + ProvenanceManager 또는 Ingest → Extract → GraphBuilder처럼 좁은 경계부터 검증하고, 이후 Decision Intelligence·Reasoning·MCP를 추가하는 순서가 안전하다.[6][7][11]

Sources

description	Python 기반 지식 그래프·에이전트 컨텍스트·결정 지능·provenance·설명 가능한 reasoning·MCP/REST 실행면을 함께 제공하는 오픈소스 프레임워크.
tags	ai-agents, open-source, python, fastapi, cli, security, github, research, harness

LLM Wiki

탐색기