Semantic Data Portal

온톨로지 기반 그래프 + 벡터 시맨틱 데이터 카탈로그 서비스입니다. 개념/데이터셋/컬럼을 속성 그래프(property graph)로 저장하고, 의미 기반 검색(semantic search)으로 데이터를 "찾아주는" 것을 목표로 합니다. 단독(standalone) 실행과 서브모듈(submodule) 임베딩을 모두 지원합니다.

그래프 엔진 (Graph Engine)

• 엔진: 단일 Postgres 인스턴스에서 Apache AGE(property graph, openCypher 그래프 순회)
  • pgvector(임베딩 KNN 시맨틱 검색)를 함께 사용합니다.
• 영속성(persistence): 모듈 전역 dict 대신 DB 백엔드로 이전. 마이그레이션(migrations/)이 그래프/벡터 스키마를 생성하고, 시드(seed)가 카탈로그 + 5개 온톨로지 개념을 멱등(idempotent)하게 적재합니다.
• 폴백(fallback): DB DSN이 없으면 의존성 없는 in-memory 백엔드로 동일 API가 동작하여 CI/서브모듈 환경에서도 그대로 실행됩니다.

새 데이터베이스 객체 (2+ word snake_case)

ontology_concepts, concept_edges(→ graph_edges), dataset_nodes, graph_nodes, embedding_vectors, config_entries, schema_migrations.

목표

• 데이터 탐색: 키워드 카탈로그 검색 + 유사어/용어(ontology) 해석 + 그래프 순회 + 시맨틱 검색
• 지식 그래프 수집(ingestion): NODES/EDGES/CONCEPTS 업스트림 푸시
• 브라우징: 스키마 조회, 샘플 미리보기, 민감 컬럼 마스킹
• 거버넌스: 정책 판단(PERMISSION), 샘플 정책 근거(Decision/Omission) 노출
• 오케스트레이션: 자연어 질문 기반 질의 후보 추천 + SQL draft 제시

첨부 문서는 다음 경로에 보관됩니다.

• docs/prd-trd.md
• docs/papers/ — 지식그래프/온톨로지/그래프+벡터 하이브리드 검색 논문(인용/요약)

로컬 실행

로컬 개발 (venv, in-memory 백엔드 — DB 불필요)

python -m venv .venv
. .venv/Scripts/Activate.ps1
python -m pip install --require-hashes -r requirements-dev.txt
PYTHONPATH=src uvicorn sdp.api:app --reload

SDP_DATABASE_URL=postgresql://...를 지정하면 policy decision과 audit event가 tenant/resource/evidence id 기준의 Postgres evidence store에 기록됩니다. SDP_DATABASE_SSLMODE=require처럼 SSL mode를 함께 지정할 수 있습니다. SDP_SQLITE_PATH=.local/sdp-evidence.sqlite3를 지정하면 production credential 없이도 같은 evidence store protocol을 로컬 SQLite fallback으로 검증할 수 있습니다. SDP_DATABASE_URL이 있으면 Postgres가 SQLite보다 우선합니다. SDP_LOG_SINK_URL=file://.local/sdp-requests.jsonl과 SDP_REQUEST_ID_HEADER=X-Request-Id를 지정하면 request id, tenant, actor, route, status, latency, evidence ids만 body 없이 request observation log로 기록됩니다. REST connector secret은 SDP_CONNECTOR_SECRET_REF_PREFIX=SDP_CONNECTOR_SECRET_ 기준의 env secret reference로 조회합니다. 예: SDP_CONNECTOR_SECRET_REST_CONNECTOR_MARKETING_CAMPAIGN_TOKEN 값은 presence만 검증하며 API 응답에는 노출하지 않습니다. OIDC token verification은 SDP_OIDC_ISSUER, SDP_OIDC_AUDIENCE, SDP_OIDC_JWKS_URL, SDP_OIDC_GROUP_ROLE_MAP를 사용합니다.

Docker 기반 로컬 데모는 다음 명령으로 실행합니다.

docker compose up --build

컨테이너는 SDP_SQLITE_PATH=/data/sdp-evidence.sqlite3를 사용하고 /health healthcheck를 노출합니다.

Postgres evidence store까지 포함한 paid-pilot 프로파일은 다음 명령으로 실행합니다.

export POSTGRES_USER=sdp_app
export POSTGRES_PASSWORD='<strong-postgres-password>'
export SDP_DATABASE_URL='postgresql://sdp_app:<url-encoded-password>@postgres:5432/sdp'
docker compose --profile postgres up --build

이 프로파일은 semantic-data-portal-postgres를 http://localhost:8001에 열고, SDP_DATABASE_URL과 POSTGRES_PASSWORD를 필수 env로 요구합니다. POSTGRES_USER는 sdp_app 기본값이 있지만 명시 설정을 권장합니다. Postgres host port는 기본적으로 127.0.0.1:54329에만 바인딩되어 managed Postgres 경로와 동일한 store protocol을 로컬에서 검증합니다.

그래프 엔진(Postgres + Apache AGE + pgvector) 프로파일은 다음 명령으로 실행합니다.

export GRAPH_POSTGRES_USER=sdp_graph_app
export GRAPH_POSTGRES_PASSWORD='<strong-graph-password>'
export SDP_DATABASE_DSN='postgresql+psycopg://sdp_graph_app:<url-encoded-password>@graph_db:5432/sdp'
docker compose --profile graph up --build
curl localhost:8002/healthz   # DB/AGE/pgvector 준비 상태 확인

sdp_api 서비스는 필수 SDP_DATABASE_DSN으로 그래프 백엔드에 연결하며, GRAPH_POSTGRES_PASSWORD도 필수입니다. GRAPH_POSTGRES_USER는 sdp_graph_app 기본값이 있지만 명시 설정을 권장합니다. 기동 시 마이그레이션 + 시드를 멱등하게 적용합니다. Graph DB host port도 기본적으로 127.0.0.1:5432에만 바인딩됩니다.

마이그레이션 + 시드 (그래프 DB 백엔드, 수동 실행)

# 부트스트랩 전송(transport) 용도로만 env 사용 — 앱 설정/시크릿은 config_entries 테이블에서 로드
SDP_DATABASE_DSN='postgresql+psycopg://sdp_graph_app:<url-encoded-password>@localhost:5432/sdp' \
  python -m migrations.run_migrations

API

Health / readiness

• GET /health — liveness
• GET /healthz — readiness (그래프 백엔드 DB/AGE/pgvector 준비 검증, 미준비 시 503)

Graph ingestion (지식 그래프 수집)

• POST /graph/nodes — 노드 업스트림 푸시
• POST /graph/edges — 엣지 업스트림 푸시
• POST /ontology/concepts — 온톨로지 개념 업스트림 푸시
• GET /graph/nodes/{node_id}
• GET /graph/stats

Graph traversal + semantic retrieval

• POST /graph/query — openCypher/BFS 그래프 순회 (edge_types/direction/max_depth, AGE 백엔드는 raw cypher 지원)
• GET /ontology/term/{term}/graph — 개념 그래프 (그래프 스토어 백엔드)
• POST /search/semantic — pgvector KNN 시맨틱 검색 (kind 필터)

Catalog / governance / enterprise (기존)

• GET /health
• GET /metrics
• GET /catalog/search?q=...
• GET /catalog/datasets
• GET /catalog/datasets/{dataset_id}
• GET /catalog/datasets/{dataset_id}/jsonld
• GET /catalog/datasets/{dataset_id}/validate
• GET /catalog/datasets/{dataset_id}/semantic-validation
• POST /policy/decision
• GET /policy/decisions
• POST /ontology/resolve
• GET /ontology/concept/{concept}
• GET /browse/{dataset_id}/schema
• POST /browse/{dataset_id}/preview
• POST /llm/search
• POST /llm/draft-query
• GET /enterprise/readiness
• GET /enterprise/demo-plan
• GET /enterprise/kpis
• GET /enterprise/controls
• GET /enterprise/rbac-matrix
• GET /enterprise/observability
• GET /enterprise/production-readiness
• GET /enterprise/evidence-pack
• GET /enterprise/shacl-validation
• GET /enterprise/steward-review
• GET /enterprise/console
• POST /enterprise/auth/oidc-preview
• POST /enterprise/auth/oidc-verify
• GET /enterprise/connectors/{connector_id}/probe

테스트

PYTHONPATH=src pytest
PYTHONPATH=src python -m sdp.demo_smoke

구현 대응 요약

PRD/TRD 항목	구현
Catalog Service	src/sdp/catalog.py, /catalog/*
Ontology / Terminology	src/sdp/ontology.py, /ontology/*
Browse/Query	src/sdp/browse.py, /browse/*
Policy Service	src/sdp/policy.py, /policy/decision
LLM Orchestrator	src/sdp/orchestrator.py, /llm/*
JSON-LD Export	/catalog/datasets/{id}/jsonld
Enterprise Core Contracts	src/sdp_core/contracts.py, src/sdp_core/readiness.py, src/sdp_core/demo_seed.py, src/sdp_core/enterprise.py, src/sdp_core/rbac.py, src/sdp/enterprise_evidence.py, src/sdp/semantic_validation.py, src/sdp/steward_review.py, src/sdp/observability.py, /enterprise/*

src/sdp_core/demo_seed.py는 buyer demo domain, SQL/RDF/file/API seed dataset, analyst/governance question을 catalog seed, /enterprise/demo-plan, connector probe가 함께 쓰는 단일 계약으로 둡니다. src/sdp/semantic_validation.py는 현재 metadata gate와 approved mapping을 SHACL 호환 리포트 형태로 노출해 /enterprise/shacl-validation과 smoke readiness가 같은 validation pass rate를 쓰게 합니다. src/sdp/steward_review.py는 SHACL 호환 validation report와 ontology patch queue를 /enterprise/steward-review에 모아 buyer handoff 전 검토 대기열을 확인하게 합니다.

요구사항 대응 증적

• PRD/TRD: docs/prd-trd.md
• 요구사항 대응 매트릭스: docs/implementation-compliance.md