# py-ontology-server-starter

온톨로지 지식 서버 스타터 — **FastAPI 시맨틱 레이어 + Apache Jena Fuseki 트리플스토어**, 소비자는 **REST와 MCP 둘 다**.

팔란티어식 객체 중심 온톨로지(Object Type / Property / Link Type)를 코드로 선언하고,
저장·질의는 W3C 표준(RDF / SPARQL 1.1)으로 처리한다. 애플리케이션 코드는 SPARQL 표준만
사용하므로 저장소를 GraphDB 등으로 교체해도 앱은 그대로다.

```
┌─ 소비자 ──────────────────────────────┐
│  AI 에이전트(MCP)      앱·사람(REST)   │
└──────────┬───────────────┬───────────┘
           │               │
   mcp_server.py       api/rest.py      ← 이중 어댑터
           └───────┬───────┘
            ontology/ + store/           ← 코어: 온톨로지 정의 + SPARQL 클라이언트
                   │
        Apache Jena Fuseki (docker)      ← 저장·SPARQL·추론
                   ▲
             ingest/ 파이프라인           ← 지식원 → RDF 변환·적재
```

## 빠른 시작

```bash
# 1. 트리플스토어 기동
docker compose up -d fuseki          # http://localhost:3030 (admin / admin)

# 2. 앱 설치
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# 3. 샘플 데이터 적재 (CSV → RDF → Fuseki)
python -m ontology_server.ingest.example_csv data/sample/organizations.csv \
  --object-type organization --push

# 4. REST 서버 기동
uvicorn ontology_server.main:app --reload
# → http://localhost:8000/docs
curl localhost:8000/objects/organization
```

## MCP 어댑터 (AI 에이전트용)

stdio 트랜스포트로 실행된다. Claude Code 프로젝트의 `.mcp.json`:

```json
{
  "mcpServers": {
    "ontology": {
      "command": "/절대경로/.venv/bin/python",
      "args": ["-m", "ontology_server.mcp_server"]
    }
  }
}
```

제공 도구: `list_object_types`(스키마 파악) · `search_objects`(타입별 인스턴스 조회) · `sparql_query`(읽기 전용 직접 질의).

## 내 도메인으로 바꾸기

1. `src/ontology_server/ontology/sample.py`를 도메인 온톨로지로 교체 — Object Type·Link Type 선언만 바꾸면 REST·MCP·질의 빌더가 따라온다.
2. `src/ontology_server/ingest/`에 지식원별 수집 모듈 추가 (`example_csv.py` 참고).
3. 외부 연계·표준 준수가 필요하면 네임스페이스를 실제 URI 체계로 정하고, OWL 스키마 문서를 함께 관리한다.

## 테스트

```bash
pytest                       # 단위 테스트 (Fuseki 불필요)
RUN_INTEGRATION=1 pytest     # Fuseki 기동 상태에서 통합 테스트 포함
```

## 구성

| 경로 | 역할 |
|:---|:---|
| `ontology/model.py` | Object/Link Type 정의 프레임워크 (팔란티어식) |
| `ontology/sample.py` | 샘플 온톨로지 — 프로젝트에서 교체하는 파일 |
| `store/sparql.py` | SPARQL 1.1 클라이언트 (저장소 교체 가능 지점) |
| `api/rest.py` | REST 어댑터 |
| `mcp_server.py` | MCP 어댑터 |
| `ingest/` | 지식원 → RDF 수집 파이프라인 |
| `docker-compose.yml` | Fuseki 기동 |

## 라이선스

MIT