LocalCrab은 로컬에서 실행하는 온톨로지 지식 서비스입니다. 문서·데이터를 9-space MetaOntology 그래프로 적재하고, 벡터·BM25·그래프를 결합한 하이브리드 검색을 MCP 인터페이스로 제공합니다. Docker 없이 SQLite(sqlite-vec 벡터 백엔드 포함)만으로 단일 머신에서 동작합니다.
AlexAI-MCP/OpenCrab을 기반으로 한 로컬 배포판 fork입니다. 파이썬 패키지명·엔트리포인트는 upstream 머지 충돌을 줄이기 위해 opencrab을 유지합니다.
호스팅 SaaS인 **OpenCrab**은 별도 서비스입니다. LocalCrab과의 관계는 관계 문서를 참고하세요.
- 로컬 우선: Docker 불필요 — SQLite 그래프·문서·벡터(sqlite-vec) 스토어. 벡터 백엔드는 Chroma로도 전환 가능(벡터 스토어 백엔드 참고).
- 9-space MetaOntology 그래프: 문법 검증 기반 노드·엣지 적재.
- 하이브리드 검색: 벡터(semantic) + BM25(키워드) + 그래프 이웃 탐색을 RRF로 통합.
- 한국어 검색 품질: OpenAI 호환 임베딩 서버(LM Studio 등) + 로컬 GGUF 폴백으로 KURE-v1 등 한국어 특화 모델 지원.
- MCP 서버: Claude Code·IDE·원격 클라이언트에 stdio 또는 직접 Streamable HTTP(
serve --transport http)로 연결. - 팩 내보내기 (선택): 구축한 그래프를 OpenCrab Pack v1 ZIP으로 내보내기 가능.
pip install -e ".[dev]"
# Python 3.11 이상 필요opencrab init
# 현재 디렉토리에 .env 생성 — LOCAL_DATA_DIR 등 기본 설정 포함opencrab serve
# STORAGE_MODE=local (기본) — SQLite(그래프·문서·벡터)로컬 모드 스토어 구성:
| 역할 | 백엔드 | 파일 (LOCAL_DATA_DIR 기준) |
|---|---|---|
| 그래프 | LocalGraphStore (SQLite BFS) |
graph.db |
| 문서 | LocalSQLDocStore (SQLite) |
doc_store.db |
| 벡터 | SqliteVecStore (기본) / ChromaStore (옵션) |
vectors.db / chroma/ |
| SQL | SQLStore (SQLite) | opencrab.db |
벡터 백엔드 기본값은 조건부입니다(
EMBEDDING_BACKEND·STORAGE_MODE에 따라 결정). 상세: 벡터 스토어 백엔드 섹션, 벡터 백엔드 매트릭스.
STORAGE_MODE=kuzu로 실행하면 그래프만 KuzuGraphStore(ladybug>=0.18, graph.kuzu)로
바뀌고 문서·벡터·SQL 스토어는 local 모드와 동일합니다. 설치: pip install ".[kuzu]".
STORAGE_MODE=pg로 실행하면 4스토어(graph/doc/sql/vector) 전부가 PostgreSQL 한
서버(POSTGRES_URL)로 통합됩니다 — PGGraphStore/PgDocStore/SQLStore(PG)/
PgVectorStore(pgvector HNSW), SQLAlchemy 공유 엔진·MVCC 다중 라이터. 설치:
pip install ".[pg]". 상세: 벡터 스토어 백엔드 섹션.
운영 권장: 기본은
STORAGE_MODE=local— graph/doc/sql/vector(sqlite-vec)를 전부 SQLite 한 규율로 통일해 백업 디렉터리 1개·정합성 관리 대상 1개로 운영합니다. 실시간 동시 write(MCP 서빙 중 백그라운드 로더)가 확정 요구이거나 벡터가 수백만 스케일로 커지면STORAGE_MODE=pg(PostgreSQL 단일 통합, 4스토어 전부 PG·MVCC 다중 라이터,pip install ".[pg]"— pgvector-migration-plan.md (B) 경로)로 이행하세요. 기존 SQLite → PG 데이터 이관은scripts/migrate_sqlite_to_pg.py(1:1 복사, 재임베딩 불필요) 참고.docker모드(Neo4j+MongoDB+PostgreSQL+Chroma 4종 혼합)는 SaaS 규모가 아니면 비권장입니다 — Neo4j/Mongo 각각의 이점이 4종 스토어를 따로 백업·버전관리·정합성 관리하는 비용을 상회하지 못합니다.
아키텍처 상세는 ARCHITECTURE.md 참고.
# 파일 인제스트 (벡터 + 문서 스토어)
opencrab ingest ./docs --recursive --extension .md,.txt,.pdf
# 하이브리드 검색
opencrab query "시스템 성능 지표 및 오류율"
# 현재 적재된 그래프 상태 확인
opencrab status
# MetaOntology 전체 문법 출력
opencrab manifeststdio (Claude Code 등):
claude mcp add localcrab -- opencrab serve또는 설정 파일에 직접 추가:
{
"mcpServers": {
"localcrab": {
"command": "opencrab",
"args": ["serve"]
}
}
}원격 접근 (직접 Streamable HTTP, Tailscale·cloudflared 등):
serve --transport http가 /mcp 엔드포인트를 직접 노출한다(supergateway 불필요). 인증이 필요하면 --auth-token-file(또는 LOCALCRAB_MCP_TOKEN)로 토큰을 지정한다. 클라이언트는 Authorization: Bearer <token> 헤더 또는 /mcp?token=<token> 쿼리 param 중 하나로 인증할 수 있다(같은 토큰, 둘 중 하나만 일치하면 통과).
# 신뢰망(예: Tailscale) 직결 — 무인증
opencrab serve --transport http --host 0.0.0.0 --port 8765
# 외부 노출(예: cloudflared 뒤) — Bearer 인증
opencrab serve --transport http --host 127.0.0.1 --port 8766 \
--auth-token-file ~/.openclaw/localcrab-mcp.token{
"mcpServers": {
"localcrab": {
"type": "http",
"url": "http://<host>:8765/mcp"
}
}
}헤더를 설정할 수 없는 클라이언트는 URL에 토큰을 실어 인증할 수 있다:
"url": "http://<host>:8765/mcp?token=<token>". 다만 쿼리 param 토큰은 액세스 로그·프록시·브라우저 히스토리에 평문 노출될 수 있으니 가능하면 헤더 방식을 우선한다.
uvicorn 단일 워커로 실행된다(serve가 강제). 원래 chroma PersistentClient 단일 프로세스 제약 때문이었고,
VECTOR_BACKEND=sqlite-vec(SQLite WAL)에서는 하드 제약이 아니나 프로세스별 in-memory BM25/임베딩 유지를 위해 1로 둔다. 무인증 인스턴스는 신뢰망에만 바인드할 것. 인증이 필요한 외부 경로는 토큰을 지정하고 클라이언트는Authorization: Bearer <token>헤더 또는?token=<token>쿼리 param으로 인증한다. 토큰이 설정되면/mcp의 POST·GET·DELETE 모두 인증을 요구한다(/healthz는 예외).
| 명령어 | 설명 |
|---|---|
opencrab init |
.env 생성 (기본 설정 템플릿) |
opencrab serve |
MCP 서버 시작 (stdio 기본; --transport http로 Streamable HTTP + 선택적 Bearer 인증) |
opencrab status |
모든 스토어 연결 상태 확인 |
opencrab ingest <path> |
파일을 벡터·문서 스토어에 인제스트 (--recursive, --extension, --pack-id) |
opencrab extract <path> |
LLM으로 노드·엣지 추출 후 그래프에 적재 (--dry-run, --api-key) |
opencrab query "<질문>" |
하이브리드 검색 (--spaces, --limit, --pack-id, --json-output) |
opencrab manifest |
MetaOntology 전체 문법 출력 (--json-output) |
opencrab ocr <path> |
이미지/문서 OCR (easyocr/tesseract/metadata 백엔드)1 |
opencrab image-context <path> |
이미지 CLIP 스타일 증거 컨텍스트 빌드1 |
opencrab export-neo4j-pack |
그래프 스냅샷을 OpenCrab Pack v1 JSONL로 내보내기 |
opencrab assemble-pack-v1 <dir> |
스테이징 디렉토리에서 Pack v1 ZIP 조립 |
opencrab packs list |
적재된 팩 목록 |
opencrab packs show <pack_id> |
팩 매니페스트 상세 |
opencrab packs backfill-pack-id |
노드·엣지에 pack_id 역보충 |
opencrab packs reindex-bm25 |
BM25 캐시 강제 재구성 |
| 그룹 | 툴 | 설명 |
|---|---|---|
| 문법·노드 | ontology_manifest |
MetaOntology OS 전체 문법 반환 |
ontology_add_node |
문법 검증 후 노드 추가/업데이트 | |
ontology_add_edge |
문법 검증 후 방향 엣지 추가 | |
| 조회 | ontology_query |
벡터+BM25+그래프 하이브리드 검색 (RRF 재랭킹, pack 필터, ReBAC 필터) |
ontology_get_node |
node_id로 단일 노드 조회 | |
ontology_list_nodes |
노드 목록 (space·pack_id 필터) | |
ontology_list_edges |
엣지 목록 (pack_id 필터) | |
| 분석 | ontology_impact |
I1–I7 임팩트 분석 |
ontology_lever_simulate |
레버 조정 시 하위 outcome 변화 시뮬레이션 | |
| 콘텐츠 팩 | content_pack_list |
적재된 팩 목록 (노드 수·타이틀) |
pack_create |
팩 신규 생성 + 노드·엣지·텍스트 인제스트 | |
pack_ingest |
기존 팩에 노드·엣지·텍스트 추가 | |
| 스키마 팩 | schema_pack_list |
사용 가능한 스키마 팩 목록 (설치 여부) |
schema_pack_install |
도메인 스키마 팩 설치 | |
schema_pack_uninstall |
스키마 팩 제거 | |
| 하니스 | harness_promotion_apply |
CrabHarness PromotionPackage 적용 (dry_run 지원) |
ReBAC/identity/promotion/billing 등 툴은 코드에 있으나 현재 MCP 미노출 상태입니다.
opencrab/mcp/tools.py에서 해당 툴을 주석 해제하면 복원됩니다.
두 가지 임베딩 백엔드를 지원합니다.
openai (기본): OpenAI 호환 임베딩 서버(LM Studio, Ollama 등)를 primary로, 로컬 GGUF를 fallback으로 쓰는 ResilientEmbeddingFunction 구조입니다. KURE-v1(한국어 특화, 1024d)이 기본 모델입니다. GGUF 폴백은 KURE-v1-Q8_0(약 635MB, 품질 우선)을 자동 다운로드하며, 외부 서버 없이도 완전 로컬로 동작할 수 있습니다(pip install "opencrab[gguf]"로 llama-cpp-python 설치 필요). 저사양 환경은 LOCAL_GGUF_PATH로 Q4_K_M(438MB) 등 다른 양자화를 지정할 수 있습니다.
local (롤백 옵션): ChromaDB 기본 EF, all-MiniLM-L6-v2 ONNX, 384d. 설정 없이 바로 동작하지만 한국어 검색 품질이 낮습니다.
| 모델 | top-1 (5건) | MRR | 정답−무관 마진 | 건당 속도 |
|---|---|---|---|---|
| minilm (롤백용, 384d ONNX) | 0/5 | 0.285 | −0.086 (무관 문서가 더 가까움) | ~0.25s 로컬 |
| KURE-v1 LM Studio (기본, 1024d) | 5/5 | 1.000 | +0.447 | ~0.06s GPU |
| KURE-v1 로컬 GGUF (폴백, 1024d) | 5/5 | 1.000 | +0.446 | ~1.07s CPU |
벡터 일치도(LM Studio ↔ 로컬 GGUF): cosine 평균 0.999853 — 폴백 전환 시에도 같은 컬렉션 그대로 사용.
참고:
openai는 모델이 아니라 백엔드(전송 방식) 입니다. OpenAI 호환/v1/embeddingsAPI면 무엇이든 쓸 수 있습니다 — 실제 OpenAI 클라우드 모델(text-embedding-3-small/-large)도, 자체호스팅 서버(LM Studio·Ollama·vLLM·HF TEI)에 올린 모델도 가능. 모델은OPENAI_EMBED_MODEL, 차원은EMBED_DIM으로 맞춥니다. 한국어 검색에는 KURE-v1을 추천합니다(번들 GGUF 폴백도 KURE라 turnkey). 단 한 컬렉션 = 한 모델 원칙으로, 모델을 바꾸면 새EMBED_COLLECTION+ 전량 재색인이 필요합니다(서로 다른 모델 벡터를 한 컬렉션에 섞지 말 것).
경량 대안 (CPU 부담 시): KURE-v1은 BGE-M3 기반(약 560M, 1024d)이라 CPU만으로는 무겁습니다.
CPU 자원이 부족하면 한국어 경량 임베딩 BM-K/KoSimCSE-roberta
(RoBERTa-base, 약 110M, 768d)를 추천합니다. KURE보다 가볍고 빠르지만 한국어 전용이며 검색 품질은
다소 낮을 수 있습니다. OpenAI 호환 서버(예: HF Text-Embeddings-Inference)에 KoSimCSE를 서빙하고
OPENAI_EMBED_MODEL, EMBED_DIM=768, 별도 EMBED_COLLECTION만 지정하면 코드 수정 없이 사용
가능합니다(전량 재색인 필요). 단 로컬 GGUF 폴백은 GGUF 빌드가 있어야 하므로 KoSimCSE에는 기본
적용되지 않습니다(원격 primary만 사용).
| 환경변수 | 기본값 | 설명 |
|---|---|---|
EMBEDDING_BACKEND |
openai |
openai = OpenAI 호환 서버(+GGUF 폴백), local = minilm(롤백) |
OPENAI_API_BASE |
http://localhost:1234/v1 |
OpenAI 호환 서버 주소. 콤마 구분으로 여러 URL 지정 시 순서대로 시도하는 체인(첫 서버 장애 → 다음 서버 → 전부 장애 시 GGUF 폴백) |
OPENAI_EMBED_MODEL |
text-embedding-kure-v1 |
서버에 로드된 모델 id |
OPENAI_API_KEY |
(없음) | 인증 필요 서버 사용 시 Bearer 토큰. 무인증 서버는 미설정 |
EMBED_DIM |
1024 |
임베딩 차원 (모델에 맞게 설정) |
LOCAL_GGUF_PATH |
(자동 다운로드) | 로컬 폴백 GGUF 경로 |
EMBED_COLLECTION |
opencrab_vectors_kure |
openai 백엔드 전용 Chroma 컬렉션명 |
OPENAI_TIMEOUT |
8.0 |
서버 응답 타임아웃(초) |
export EMBEDDING_BACKEND=openai
export OPENAI_API_BASE=http://<server-host>:1234/v1
export OPENAI_EMBED_MODEL=text-embedding-kure-v1
opencrab serve다중 원격 엔드포인트(장애 대비): OPENAI_API_BASE에 콤마로 여러 URL을 나열하면
순서대로 시도된다. 첫 서버가 죽어도 GGUF(CPU) 폴백으로 내려가기 전에 다음 서버를
우선 시도한다. 각 엔드포인트는 독립적으로 헬스 TTL을 추적하므로, 죽어 있는 서버
하나가 매 요청마다 지연을 만들지 않는다. 모든 엔드포인트가 동일 모델(KURE-v1)을
서빙한다고 가정한다(컬렉션 재사용 보장).
export OPENAI_API_BASE="http://embed-host-1:1234/v1,http://embed-host-2:1234/v1"롤백: EMBEDDING_BACKEND=local → minilm 컬렉션으로 즉시 복귀(단, VECTOR_BACKEND=sqlite-vec와는 조합 불가 — 아래 벡터 스토어 백엔드 참고).
기존에 local(minilm) 컬렉션으로 적재해둔 노드가 있고 openai(KURE)로 전환하는 경우, 기존 노드를 새 컬렉션으로 재임베딩해야 합니다.
export EMBEDDING_BACKEND=openai
backfill_kure.py는 이 레포에 포함되어 있지 않은 외부 운영 스크립트입니다(~/opencrab-dump쪽에서 관리, vector/doc upsert 전용). 위 환경변수를 설정한 뒤 해당 운영 스크립트를 실행해 재임베딩하세요. 상세: docs/ingestion-via-mcp-plan.md.
임베딩 백엔드(EMBEDDING_BACKEND)와 독립된 축으로, 벡터를 어디에 저장·검색할지 고릅니다.
VECTOR_BACKEND를 명시하지 않으면 아래 규칙으로 조건부 결정됩니다.
STORAGE_MODE=local(또는kuzu) +EMBEDDING_BACKEND=openai(기본) →sqlite-vecSTORAGE_MODE=pg→pgvector(4스토어 PG 통합의 벡터 축)STORAGE_MODE=docker이거나EMBEDDING_BACKEND=local(minilm) →chromaVECTOR_BACKEND를 명시하면 항상 그 값이 우선합니다.- 예외:
VECTOR_BACKEND=sqlite-vec를 명시했는데EMBEDDING_BACKEND=local이면 기동 시ValueError(minilm 384d는 sqlite-vec에서 미지원).
모드×옵션 조합 전체 매트릭스와 백엔드별 장단점 상세는 벡터 스토어 백엔드 매트릭스 참고.
sqlite-vec (로컬 모드 기본): sqlite-vec(vec0) — 벡터를 graph/doc/sql 과 같은 SQLite WAL 규율에 편입해
Chroma의 "다중 프로세스 동시 쓰기 불가"(자작 flock 층)를 제거합니다. 앱이 KURE EF로 직접 임베딩 후
vec0 테이블에 INSERT하므로 EMBEDDING_BACKEND=openai(KURE 1024d)와 함께 씁니다. 벡터 DB는
LOCAL_DATA_DIR/vectors.db. 설계·트레이드오프: docs/pgvector-migration-plan.md (A) 경로.
특성: pack-scoped 검색은 매우 빠르나(수 ms), 전역(pack 미지정) 검색은 기본 브루트포스라 대규모에서 느립니다. 전역 고속화는
VECTOR_ANN=binary(binary 2단계 양자화, 기본 off) 옵트인으로 제공 — 상세·마이그레이션·롤백은 벡터 백엔드 매트릭스 §4.1 참고. 정확도는 exact라 Chroma HNSW보다 높습니다.
chroma (docker 모드 기본 / local+minilm 조합 기본): ChromaDB. 로컬은 PersistentClient, docker는 HttpClient. 기존 동작 100% 보존.
pgvector (STORAGE_MODE=pg에서 자동 선택): PostgreSQL 확장. HNSW 인덱스
(m=16, ef_construction=64, 쿼리 시 hnsw.ef_search=PG_EF_SEARCH 기본 500)로
전역 검색도 179,784건 전량 실측 p95 24.61ms — sqlite-vec의 binary 2단계 같은 별도 가속이 불필요.
pip install ".[pg]" 필요. STORAGE_MODE!=pg에서도 VECTOR_BACKEND=pgvector를
명시하면 벡터만 PG로 보낼 수 있습니다. 설계·실측: docs/pgvector-migration-plan.md (B) 경로.
| 환경변수 | 기본값 | 설명 |
|---|---|---|
VECTOR_BACKEND |
(미설정 — 위 조건부 규칙으로 결정) | chroma | sqlite-vec | pgvector |
VECTOR_DB_FILE |
vectors.db |
sqlite-vec 벡터 DB 파일명(LOCAL_DATA_DIR 하위) |
VECTOR_COLLECTION |
vectors_kure |
sqlite-vec vec0 테이블명 |
VECTOR_ANN |
(미설정 = off) | binary = 전역 검색 2단계 양자화 가속(sqlite-vec 전용) |
VECTOR_ANN_COARSE_K |
512 |
binary 2단계 coarse 후보 수(recall 튜닝) |
PG_EF_SEARCH |
500 |
pgvector HNSW 쿼리 세션 파라미터(recall/속도 트레이드오프, pgvector 전용) |
# 기존 Chroma 컬렉션이 있는 상태에서 sqlite-vec로 전환(KURE 벡터를 그대로 1:1 이관)
python scripts/migrate_chroma_to_sqlite_vec.py # chroma → vectors.db
export EMBEDDING_BACKEND=openai VECTOR_BACKEND=sqlite-vec
opencrab serve무중단 적재(sqlite-vec): chroma의
chroma.lock(LOCK_EX)제약이 사라져 적재 시 게이트웨이/서비스를 중단할 필요가 없다. 벡터를 포함한 4스토어가 모두 SQLite WAL이라 로더/reingest 쓰기와 serve 읽기가 동시 진행되고, 라이터는write.lock/SQLitebusy_timeout(5s)로 직렬화된다. (chroma 백엔드에서는 기존대로 오프라인--fresh적재 시 중단 필요.)
롤백: VECTOR_BACKEND=chroma 명시 → Chroma 스택으로 즉시 복귀(비파괴, Chroma 보존).
# STORAGE_MODE=pg — 4스토어(graph/doc/sql/vector) 전부 PostgreSQL 한 서버로 통합
pip install ".[pg]"
export STORAGE_MODE=pg
export POSTGRES_URL=postgresql://opencrab:opencrab@localhost:5432/opencrab
opencrab serve
# 기존 로컬 SQLite(graph.db/doc_store.db/opencrab.db/vectors.db) → PG 1회 이관
# (재임베딩 없음 — vectors.db의 raw float 벡터를 그대로 복사)
python scripts/migrate_sqlite_to_pg.py --pg-url "$POSTGRES_URL" --dry-run
python scripts/migrate_sqlite_to_pg.py --pg-url "$POSTGRES_URL" --verify| 환경변수 | 기본값 | 설명 |
|---|---|---|
ANTHROPIC_API_KEY |
(없음) | opencrab extract의 --api-key 미지정 시 폴백(Claude 모델 호출용) |
OPENCRAB_BM25_NODE_LIMIT |
50000 |
BM25 인덱스가 doc 스토어에서 로드하는 노드 상한(인덱스 빌드 시간·메모리 제한). 상세: ARCHITECTURE.md §6 |
OPENCRAB_BM25_DEBOUNCE |
1.5 |
BM25 백그라운드 재빌드 디바운스(초) — 연속 ingest를 1회 재빌드로 합침. 상세: ARCHITECTURE.md |
OPENCRAB_AUTO_PACK_MIN_SCORE |
10.0 |
자동 팩 선택(키워드 기반 결정적 스코어링)에서 top-1 후보를 채택하는 최소 점수. 미달 시 팩 필터 없이 조회 |
| Space | 역할 |
|---|---|
subject |
주체 — identity·agency·역할·권한을 가진 행위자 |
resource |
자원 — 문서·데이터셋·도구·API·파일·프로젝트 |
evidence |
증거 — 원시 관측·로그·텍스트 단위·OCR 출력·실증 기록 |
concept |
개념 — 엔티티·주제·클래스·도메인 추상 |
claim |
주장 — 증거에 근거한 파생 단언 |
community |
커뮤니티 — 연관 개념 또는 행위자의 클러스터·요약 |
outcome |
결과 — KPI·리스크·임팩트·측정 가능한 결과 |
lever |
레버 — outcome·concept에 영향을 주는 조정 가능한 제어값 |
policy |
정책 — 접근·민감도·승인·거버넌스 규칙 |
opencrab/grammar/manifest.py의 META_EDGES·SPACES·NODE_TYPES를 수정해 도메인별 엣지 관계와 노드 타입을 추가할 수 있습니다. 기존 공개 문법은 opencrab manifest로 확인하세요.
STORAGE_MODE=docker로 외부 서비스에 연결합니다.
STORAGE_MODE=docker opencrab serve| 역할 | 백엔드 |
|---|---|
| 그래프 | Neo4j (NEO4J_URI, NEO4J_DATABASE) |
| 문서 | MongoDB (MONGODB_URI) |
| 벡터 | Chroma HTTP (CHROMA_HOST:CHROMA_PORT) |
| SQL | PostgreSQL (POSTGRES_URL) |
SQLite 버전 요구사항: 로컬 모드는
json_extract()사용으로 SQLite 3.9.0 이상이 필요합니다.python3 -c "import sqlite3; print(sqlite3.sqlite_version)"로 확인하세요.로컬 모드 ReBAC 제약: 그래프 권한 탐색이 Python BFS(
find_neighbors())로 동작합니다. 직접 및 전이적(member_of/manages → permission) 경로는 완전 지원. depth 2 초과 복잡한 다중 홉 패턴은 미지원.
# Dry-run: 연결 및 데이터 수량 확인 (쓰기 없음)
uv run python scripts/migrate_to_local.py --dry-run
# 실제 마이그레이션 (기존 로컬 DB 파일 자동 백업)
uv run python scripts/migrate_to_local.py구축한 그래프를 OpenCrab Pack v1 ZIP으로 내보낼 수 있습니다.
manifest.json
graph/nodes.jsonl
graph/edges.jsonl
evidence/index.jsonl
quality/report.json
neo4j/import.cypher
neo4j/opencrab_ingest.jsonl
neo4j/export_status.json
README.md
sample_queries.json
community_reports.json
포맷 상세: OpenCrab Pack v1 ZIP 형식
crabharness/는 대규모 수집·파싱 작업을 위한 미션 기반 증거 수집 제어판입니다. 크롤 대상·범위·성공 기준을 미션으로 동결하고, 증거 번들을 검증한 뒤 PromotionPackage를 생성합니다. 상세는 CrabHarness README 참고.
make dev-install # 의존성 설치 (개발 모드)
make seed # 샘플 온톨로지 시드 데이터 로드
make test # 전체 테스트 실행
make status # 스토어 연결 상태 확인
make manifest # MetaOntology 문법 출력
make lint # ruff 코드 검사
make format # black + isort 포매팅
make coverage # 커버리지 리포트통합 테스트 (Neo4j·MongoDB·Chroma 도커 필요):
OPENCRAB_INTEGRATION=1 pytest tests/ -vSTORAGE_MODE=pg (PGGraphStore/PgDocStore) 골든 파리티 테스트는 별도의 로컬
PostgreSQL 인스턴스가 필요하며, OPENCRAB_PG_TEST_URL 미설정 시 자동으로
skip됩니다. 실제 데이터 손상을 막기 위해 DB명이 _test로 끝나지 않으면
tripwire 테스트가 실패합니다 — 반드시 전용 테스트 DB를 사용하세요.
docker compose up -d postgres # pgvector/pgvector:pg16 기동
docker exec opencrab-postgres createdb -U opencrab opencrab_test # 최초 1회
make test-pg # OPENCRAB_PG_TEST_URL 자동 설정 후 실행CI(.github/workflows/ci.yml)는 동일한 구성을 postgres 서비스 컨테이너로
띄워 매 PR마다 실행합니다.
opencrab/
grammar/ MetaOntology 문법, 검증기, 용어집
schemas/ YAML 타입 스키마, 스키마 팩, 액션 스키마
ontology/ 빌더, 쿼리, identity, 정규화, 승인, ReBAC
execution/ 워크플로·승인 런타임
stores/ Local(SQLite)·Kuzu(ladybug)·PG(pgvector)·docker(Neo4j/Mongo/Chroma) 스토어 + 임베딩 EF
mcp/ MCP 서버 및 툴 레지스트리
crabharness/
crabharness/ 미션 플래너, 런타임, 검증, 프로모션 패키지 빌더
codex_workers/ 크롤러·수집기 플러그인 워커
missions/ 예제 미션
docs/ 아키텍처, 팩 형식, 관계 문서
MIT. AlexAI-MCP/OpenCrab 기반 fork.