4. CLI 레퍼런스 (claire)
`claire`는 Claire Bible 시스템의 통합 애플리케이션 진입점(Entrypoint)입니다. 컨테이너 내부 프로세스와 로컬 개발 환경 모두 동일한 CLI 인터페이스를 공유합니다.
4.1 진입점 및 실행 방법
실행 환경에 따라 다음과 같이 명령을 실행합니다:
-
로컬 소스 개발 환경: 가상환경과 로컬 소스를 사용하여 실행합니다.
uv run claire <명령어> [옵션] -
프로덕션 컨테이너 호스트 환경: 배포된 컨테이너 내부의 데이터와 환경변수를 참조하여 one-off 명령을 실행합니다.
./cb-manuscript app <명령어> [옵션]
4.2 시스템 진단 및 상태 확인
| 명령어 | 목적 | 설명 |
|---|---|---|
|
환경 및 의존성 진단 |
Python 버전, 필수 라이브러리, SQLite 버전, 벡터 확장 백엔드( |
|
건강 상태 JSON 출력 |
데이터베이스 연결성, 스키마 마이그레이션 버전, 수집 큐(Queue) 대기열 크기, 에러 인박스(Error Inbox) 상태를 JSON 형식으로 출력합니다. |
|
시스템 요약 현황 |
현재 등록된 총 문서 수, 엔티티 수, 관찰 사실 수, 관계 수 및 최근 처리 로그를 보기 쉬운 테이블로 요약합니다. |
|
온톨로지 통계 분석 |
엔티티 타입별 분포, 관계 술어별 연결 빈도, 고차수(High-degree) 허브 노드 통계를 출력합니다. |
|
읽기 전용 생존 점검 |
데이터베이스와 스키마의 무결성을 조회하여 헬스체크 통과 여부를 0(성공) 또는 1(실패) 종료 코드로 반환합니다. |
사용 예시
# 전체 시스템 의존성 및 환경 검사
uv run claire doctor
# 시스템 건강 상태 JSON 확인
uv run claire health4.3 데이터 적재 및 검색
1. ingest — 자료 단건 적재
URL 링크, 로컬 텍스트 파일, 또는 직접 입력한 텍스트 메모를 지식베이스에 적재합니다.
# 웹 문서 URL 적재
uv run claire ingest "https://example.com/tech-article"
# 1홉 외부 링크까지 함께 적재
uv run claire ingest "https://example.com/tech-article" --expand
# 직접 텍스트 메모 적재
uv run claire ingest "Kubernetes v1.30 출시: 메모리 스왑 정식 지원 및 보안 강화"-
--expand: 본문 내 주요 관련 링크를 1홉 깊이까지 자동 분석하여 확장 적재합니다.
2. search — 하이브리드 검색 및 LLM 정리
키워드를 바탕으로 FTS5 전문 검색과 벡터 검색을 결합하여 결과를 찾고, AI가 인용을 포함하여 요약 답변을 생성합니다.
# 하이브리드 검색 및 AI 답변 생성
uv run claire search "팔란티어 온톨로지 모델"
# LLM 요약 없이 순수 검색 결과 목록만 출력
uv run claire search "팔란티어 온톨로지 모델" --no-summary4.4 서비스 구동 명령
| 명령어 | 프로세스 유형 | 설명 |
|---|---|---|
|
텔레그램 봇 |
Telegram Bot API와 long-polling 방식으로 통신하며 수신된 메시지와 링크를 자동 인제스트합니다. |
|
웹 및 API 서버 |
Starlette / Uvicorn 기반의 HTTP API 및 인터랙티브 웹 UI 프론트엔드 서비스를 기동합니다. |
사용 예시
# 웹 UI 및 API 서버 실행 (기본 127.0.0.1:8765)
uv run claire serve-api
# 텔레그램 봇 실행
uv run claire bot4.5 백그라운드 루프 및 자동 복구
Claire Bible은 일시적인 네트워크 장애나 모델 오류로 실패한 작업을 자가 복구하는 다양한 백그라운드 워커 명령을 지원합니다.
1. 에러 인박스 복구 (recover)
일시적 오류로 실패한 수집 건을 지수 백오프(Exponential Backoff)를 적용하여 안전하게 재처리합니다.
# 복구 대기열 1회 일괄 처리
uv run claire recover-run
# 백그라운드 무한 루프로 실행 (데몬 모드)
uv run claire recover-loop
# 에러 인박스에 저장된 모든 실패 건 수동 전량 재적재
uv run claire replay-failed2. 문서 최신화 (refresh)
오래되었거나 내용이 빈약한 문서를 원래의 문서 ID를 보존한 채 최신 웹 원문으로 다시 스크랩합니다.
# 재수집 대상 마킹
uv run claire refresh-mark --older-than 30d
# 마킹된 문서 1회 재수집
uv run claire refresh-run
# 백그라운드 갱신 루프 구동
uv run claire refresh-loop4.6 스키마 마이그레이션 (migrate)
SQLite 데이터베이스 스키마를 최신 버전으로 안전하게 업그레이드합니다.
uv run claire migrate