semantica

Explorer를 시작하기 전에 정확한 브라우저 origin이 포함되도록 ALLOWED_ORIGINS(또는 EXPLORER_CORS_ORIGINS)를 설정하세요. 기본적으로 http://localhost:5173과 http://127.0.0.1:5173만 허용되며, 동일한 허용 목록이 /ws/graph-updates WebSocket 핸드셰이크에도 적용됩니다.

포트 8020의 경우 다음을 실행하세요:

ALLOWED_ORIGINS="http://127.0.0.1:8020,http://localhost:8020" \
semantica-explorer --graph any_graph.json --port 8020

그런 다음 http://127.0.0.1:8020을 열고, 변수를 변경한 후 서버를 재시작하세요. 이 문제는 Semantica 0.6.7에서 확인되었습니다.

선택적 종속성을 설치하거나, slim-core 환경에서 Node2Vec 테스트를 건너뛰세요.

전체 테스트 환경의 경우:

pip install -e ".[dev,graph-embeddings]"

이 명령은 gensim>=4.4.0을 설치합니다. 설치되면 영향을 받는 모든 Node2Vec 테스트가 통과해야 합니다.

gensim이 의도적으로 없는 경우, 영향을 받는 각 테스트 모듈의 상단에 다음 가드를 추가하세요:

pytest.importorskip("gensim")  # Node2Vec requires semantica[graph-embeddings]

다음 파일에 있는 8개의 테스트에 적용하세요:
- tests/context/test_banking_context_graphs_e2e.py
- tests/context/test_context_explainability_regression.py
- tests/kg/test_enhanced_algorithms_e2e.py
- tests/kg/test_provenance_integration.py
- tests/test_030_realworld_comprehensive.py
- tests/vector_store/test_decision_embedding_pipeline.py

gensim 검사를 NodeEmbedder.__init__에서 _train_word2vec()로 옮기지 마세요. slim-core 계약은 생성자가 예외를 발생시키는 것에 의도적으로 의존하며, 이를 통해 호출자가 Node2Vec을 정상적으로 비활성화할 수 있습니다. 이 동작을 필요로 하는 테스트는 test_node_embedder_gensim_missing_hint, test_agent_context_with_graph_builds_without_gensim, test_graph_components_without_gensim_keep_everything_but_node2vec입니다.

virtualenv에 선택적 의존성을 설치하세요:

pip install -e ".[graph-embeddings]"

또는 릴리스된 패키지의 경우:

pip install "semantica[graph-embeddings]"

그런 다음 다시 실행하세요:

python -m pytest tests/kg/test_node_embeddings.py -q

리포지토리 테스트 수정의 경우, test_init_gensim_unavailable와 test_init_invalid_method는 gensim 없이 실행되어야 하므로 모듈 수준의 pytest.importorskip("gensim")를 추가하지 마세요. 대신 다음을 수행하세요:

1. pyproject.toml에 마커를 등록하세요:

[tool.pytest.ini_options]
markers = [
    "no_gensim: test runs without the optional gensim dependency"
]

2. 테스트에 no_gensim 마커가 지정되지 않은 한 gensim 의존 테스트를 건너뛰는 autouse 픽스처를 추가하세요:

import pytest
from semantica.kg.node_embeddings import GENSIM_AVAILABLE

@pytest.fixture(autouse=True)
def require_gensim(request):
    if not GENSIM_AVAILABLE and "no_gensim" not in request.keywords:
        pytest.skip("Install semantica[graph-embeddings] to run Node2Vec tests")

3. test_init_gensim_unavailable와 test_init_invalid_method에 @pytest.mark.no_gensim 마커를 지정하세요.

gensim이 없을 때 예상되는 결과: 2개 통과, 31개 건너뜀. gensim이 설치된 경우: 33개 테스트 모두 통과.

CSVExporter.export_relationships()는 엔드포인트 필드 이름으로 source/source_id와 target/target_id만 인식합니다. 백엔드 형식의 레코드는 start_node_id/end_node_id(Neo4j, FalkorDB, Neptune 및 이름이 변경된 AGE 엣지) 또는 start_id/end_id(raw AGE)를 사용하므로, 정규화 경로는 아무런 오류나 경고 없이 빈 엔드포인트 컬럼을 기록합니다. 수정/우회 방법:

1. **수정(패치)**: semantica/export/csv_exporter.py(export_relationships)에서 메서드 시작 시 레코드를 semantica/export/endpoint_names.py의 canonical_endpoints(SOURCE_ENDPOINT_NAMES/TARGET_ENDPOINT_NAMES를 정의함)를 통해 처리하세요. 이는 Parquet 및 Arrow 익스포터가 이미 사용하고 있는 것과 동일한 방식입니다. 이렇게 하면 모든 백엔드 표기법이 source_id/target_id로 매핑되며, source/target 및 source_id/target_id도 이전과 동일하게 작동합니다.

2. **우회 방법(코드 변경 없음)**: 내보내기 전에 필드 이름을 변경하세요:

record = {"id": "r1", "start_node_id": "alice", "end_node_id": "acme", "type": "WORKS_AT"}
record["source_id"], record["target_id"] = record.pop("start_node_id"), record.pop("end_node_id")
CSVExporter().export_relationships([record], "rel.csv")

3. **대체 경로**: export({"edges": [record]})는 값을 보존하지만 정규화 없이 원래 컬럼 이름(start_node_id/end_node_id)으로 기록합니다. Parquet 및 Arrow 익스포터는 영향을 받지 않습니다.

FileObject 인스턴스는 GraphBuilder._process_item()이 이를 인식하지 못하기 때문에 아무런 알림 없이 건너뜁니다. 이 메서드는 텍스트 문자열이나 {"text": ...}와 같은 딕셔너리를 예상합니다. 임시 해결 방법으로, 그래프를 빌드하기 전에 수집된 각 FileObject를 변환하세요:

docs = FileIngestor().ingest_directory("./docs/", recursive=True)
kg = GraphBuilder(merge_entities=True, enable_temporal=True).build(
    [{"text": d.text} for d in docs]
)

PR #1951의 영구 수정 사항은 build()가 FileObject.text에서 텍스트를 직접 추출하도록 하고, 지원되지 않는 소스 타입을 아무 알림 없이 건너뛰는 대신 해당 타입의 이름을 명시하는 경고를 로깅합니다. PR #1951이 포함된 릴리스로 업데이트하거나, main에서 실행 중이라면 해당 변경 사항을 적용하세요.