codebuff-agent 2.1.74__py3-none-any.whl

codebuff_core/models/rag.py

@@ -0,0 +1,300 @@
+"""
+RAG 설정 및 API Pydantic 모델
+
+로컬 RAG 시스템을 위한 설정 스키마 정의:
+- Qdrant 벡터 데이터베이스 설정
+- 임베딩 모델 설정
+- 문서 청킹 설정
+- 파일 감시(watchdog) 설정
+- 검색 API 요청/응답 모델
+"""
+
+import os
+from typing import Optional, List, Literal, Dict, Any
+from pydantic import BaseModel, Field
+
+
+class QdrantConfig(BaseModel):
+    """Qdrant 벡터 데이터베이스 설정"""
+
+    mode: Literal["local", "server", "cloud"] = Field(
+        default="local",
+        description="배포 모드: local (파일 기반), server (Docker), cloud",
+    )
+    # 로컬 모드 설정
+    local_path: Optional[str] = Field(
+        default=None,
+        description="로컬 Qdrant 저장소 경로. 기본값: $QDRANT_PATH, 없으면 $CODEBUFF_HOME/qdrant, 없으면 ~/.codebuff/qdrant",
+    )
+    # 서버 모드 설정
+    url: Optional[str] = Field(
+        default="http://localhost:6333",
+        description="server/cloud 모드용 Qdrant 서버 URL",
+    )
+    api_key: Optional[str] = Field(default=None, description="cloud 모드용 API 키")
+    # 컬렉션 설정
+    collection_name: str = Field(
+        default="hdsp_knowledge", description="벡터 컬렉션 이름"
+    )
+
+    def get_mode(self) -> str:
+        """Qdrant 배포 모드 반환"""
+        return self.mode
+
+    def get_url(self) -> str:
+        """Qdrant 서버 URL 반환"""
+        return self.url or "http://localhost:6333"
+
+    def get_local_path(self) -> str:
+        """해석된 로컬 경로 반환"""
+        if self.local_path:
+            return os.path.expanduser(self.local_path)
+        from codebuff_core.legacy_paths import resolve_home
+
+        return str(resolve_home("qdrant"))
+
+
+class EmbeddingConfig(BaseModel):
+    """임베딩 모델 설정"""
+
+    model_name: str = Field(
+        default="intfloat/multilingual-e5-small",
+        description="임베딩용 HuggingFace 모델 이름",
+    )
+    device: Literal["cpu", "cuda", "mps"] = Field(
+        default="cpu", description="임베딩 계산용 디바이스"
+    )
+    batch_size: int = Field(default=32, description="임베딩 생성 배치 크기")
+    cache_folder: Optional[str] = Field(
+        default=None, description="모델 캐시 폴더. 기본값: ~/.cache/huggingface"
+    )
+    # 모델별 설정
+    normalize_embeddings: bool = Field(
+        default=True, description="코사인 유사도를 위한 임베딩 정규화"
+    )
+
+    def get_model_name(self) -> str:
+        """임베딩 모델 이름 반환"""
+        return self.model_name
+
+    def get_device(self) -> str:
+        """임베딩 계산 디바이스 반환"""
+        return self.device
+
+
+class ChunkingConfig(BaseModel):
+    """문서 청킹 설정"""
+
+    chunk_size: int = Field(default=512, description="목표 청크 크기 (문자 단위)")
+    chunk_overlap: int = Field(default=50, description="청크 간 중첩 (문자 단위)")
+    split_by_header: bool = Field(
+        default=True, description="의미적 경계를 위해 마크다운을 헤더 기준으로 분할"
+    )
+    min_chunk_size: int = Field(default=100, description="포함할 최소 청크 크기")
+    max_chunk_size: int = Field(default=2000, description="최대 청크 크기 (하드 리밋)")
+
+
+class WatchdogConfig(BaseModel):
+    """파일 모니터링 설정"""
+
+    enabled: bool = Field(default=True, description="파일 시스템 모니터링 활성화")
+    debounce_seconds: float = Field(
+        default=2.0, description="파일 변경 이벤트 디바운스 시간"
+    )
+    patterns: List[str] = Field(
+        default=["*.md", "*.py", "*.txt", "*.json"], description="모니터링할 파일 패턴"
+    )
+    ignore_patterns: List[str] = Field(
+        default=[".*", "__pycache__", "*.pyc", "*.egg-info"], description="무시할 패턴"
+    )
+
+
+class RAGConfig(BaseModel):
+    """메인 RAG 시스템 설정"""
+
+    enabled: bool = Field(default=True, description="RAG 시스템 활성화")
+    knowledge_base_path: Optional[str] = Field(
+        default=None, description="지식 베이스 경로. 기본값: 내장 libraries/"
+    )
+    qdrant: QdrantConfig = Field(default_factory=QdrantConfig)
+    embedding: EmbeddingConfig = Field(default_factory=EmbeddingConfig)
+    chunking: ChunkingConfig = Field(default_factory=ChunkingConfig)
+    watchdog: WatchdogConfig = Field(default_factory=WatchdogConfig)
+
+    # 검색 설정
+    top_k: int = Field(default=5, description="검색할 청크 수")
+    score_threshold: float = Field(default=0.3, description="최소 유사도 점수 임계값")
+    max_context_tokens: int = Field(
+        default=1500, description="RAG 컨텍스트 주입 최대 토큰"
+    )
+
+    def is_enabled(self) -> bool:
+        """RAG 활성화 여부 확인"""
+        return self.enabled
+
+    def get_knowledge_base_path(self) -> Optional[str]:
+        """지식 베이스 경로 반환"""
+        if self.knowledge_base_path:
+            return os.path.expanduser(self.knowledge_base_path)
+        return None  # 내장 기본값 사용
+
+
+# ============ API 요청/응답 모델 ============
+
+
+class SearchRequest(BaseModel):
+    """명시적 RAG 검색 요청 본문"""
+
+    query: str = Field(description="검색 쿼리")
+    top_k: Optional[int] = Field(default=None, description="기본 top_k 오버라이드")
+    filters: Optional[Dict[str, Any]] = Field(
+        default=None, description="메타데이터 필터 (예: {'source_type': 'library'})"
+    )
+    include_score: bool = Field(default=True, description="결과에 관련성 점수 포함")
+
+
+class SearchResult(BaseModel):
+    """단일 검색 결과"""
+
+    content: str = Field(description="청크 내용")
+    score: float = Field(description="관련성 점수 (0-1)")
+    metadata: Dict[str, Any] = Field(description="청크 메타데이터 (소스, 유형 등)")
+
+
+class SearchResponse(BaseModel):
+    """RAG 검색 응답 본문"""
+
+    results: List[SearchResult] = Field(description="관련성순으로 정렬된 검색 결과")
+    query: str = Field(description="원본 쿼리")
+    total_results: int = Field(description="총 일치 청크 수")
+
+
+class IndexStatusResponse(BaseModel):
+    """인덱스 상태 응답 본문"""
+
+    ready: bool = Field(description="RAG 시스템 준비 여부")
+    total_documents: int = Field(default=0, description="총 인덱싱된 문서 수")
+    total_chunks: int = Field(default=0, description="총 인덱싱된 청크 수")
+    last_updated: Optional[str] = Field(
+        default=None, description="마지막 인덱스 업데이트 타임스탬프"
+    )
+    knowledge_base_path: Optional[str] = Field(
+        default=None, description="현재 지식 베이스 경로"
+    )
+
+
+class ReindexRequest(BaseModel):
+    """수동 재인덱싱 요청 본문"""
+
+    force: bool = Field(
+        default=False, description="파일이 변경되지 않아도 전체 재인덱싱 강제"
+    )
+    path: Optional[str] = Field(
+        default=None, description="재인덱싱할 특정 파일 또는 디렉토리"
+    )
+
+
+class ReindexResponse(BaseModel):
+    """재인덱싱 작업 응답 본문"""
+
+    success: bool = Field(description="재인덱싱 성공 여부")
+    indexed: int = Field(description="인덱싱된 파일 수")
+    skipped: int = Field(description="건너뛴 파일 수 (변경 없음)")
+    errors: List[Dict[str, str]] = Field(default=[], description="인덱싱 오류 목록")
+
+
+# ============ 디버그 모델 ============
+
+
+class ChunkDebugInfo(BaseModel):
+    """디버깅용 청크 상세 점수 정보"""
+
+    chunk_id: str
+    content_preview: str  # 처음 200자
+    score: float  # 벡터 유사도 점수 (0-1)
+    rank: int  # 순위
+    metadata: Dict[str, Any]  # source, section 등
+    passed_threshold: bool  # 임계값 통과 여부
+
+
+class LibraryDetectionDebug(BaseModel):
+    """라이브러리 감지 단계 디버그 정보"""
+
+    input_query: str
+    imported_libraries: List[str]
+    available_libraries: List[str]
+    detected_libraries: List[str]
+    detection_method: str
+
+
+class SearchConfigDebug(BaseModel):
+    """검색 설정 정보"""
+
+    top_k: int
+    score_threshold: float
+    max_context_tokens: int
+
+
+class DebugSearchRequest(BaseModel):
+    """디버그 검색 요청"""
+
+    query: str = Field(description="디버깅용 검색 쿼리")
+    imported_libraries: List[str] = Field(
+        default=[], description="검색 필터링을 위한 import된 라이브러리 목록"
+    )
+    top_k: Optional[int] = Field(default=None, description="기본 top_k 오버라이드")
+    include_full_content: bool = Field(
+        default=False, description="미리보기 대신 전체 내용 포함"
+    )
+    simulate_plan_context: bool = Field(
+        default=True, description="계획 생성 시와 같은 포맷된 컨텍스트 생성"
+    )
+
+
+class DebugSearchResponse(BaseModel):
+    """디버그 검색 응답"""
+
+    library_detection: LibraryDetectionDebug
+    config: SearchConfigDebug
+    chunks: List[ChunkDebugInfo]
+    total_candidates: int
+    total_passed_threshold: int
+    search_ms: float  # 벡터 검색 시간 (밀리초)
+    formatted_context: str
+    context_char_count: int
+    estimated_context_tokens: int
+
+
+# ============ 팩토리 함수 ============
+
+
+def get_default_rag_config() -> RAGConfig:
+    """ConfigManager JSON에서 RAG 설정 로드"""
+    from codebuff_core.managers.config_manager import get_config_manager
+
+    cfg = get_config_manager().get_config()
+    rag = cfg.get("rag", {})
+
+    # 환경변수 우선 → config 파일 폴백
+    qdrant_mode = os.environ.get("QDRANT_MODE", "") or rag.get("qdrantMode", "local")
+    qdrant_url = os.environ.get("QDRANT_URL", "") or rag.get("qdrantUrl", "http://localhost:6333")
+    qdrant_path = os.environ.get("QDRANT_PATH", "") or rag.get("qdrantPath")
+    qdrant_api_key = os.environ.get("QDRANT_API_KEY", "") or rag.get("qdrantApiKey")
+
+    return RAGConfig(
+        enabled=rag.get("enabled", True),
+        knowledge_base_path=rag.get("knowledgeBasePath"),
+        qdrant=QdrantConfig(
+            mode=qdrant_mode,
+            url=qdrant_url,
+            local_path=qdrant_path or None,
+            api_key=qdrant_api_key or None,
+            collection_name=rag.get("collectionName", "hdsp_knowledge"),
+        ),
+        embedding=EmbeddingConfig(
+            model_name=rag.get("embeddingModel", "intfloat/multilingual-e5-small"),
+            device=rag.get("embeddingDevice", "cpu"),
+        ),
+        chunking=ChunkingConfig(),
+        watchdog=WatchdogConfig(),
+    )

codebuff_core/platform_rules.py

@@ -0,0 +1,127 @@
+"""사내 BDP 플랫폼(HDSP 노트북) 실행 환경 규칙 — 두 엔진이 같이 쓰는 정본 (이슈 #120).
+
+HDSP 노트북 pod 에서는 boto3 를 직접 쓸 수 없다. 기본 자격증명·SSL 경로가 막혀 있어서
+(`secrets_bootstrap.py` 주석 참고) 미리 설치된 bdpengine 의 클라이언트 팩토리를 거쳐야
+Athena·S3·SageMaker·MinIO 에 닿는다. 모델이 이것을 모르면 boto3 로 코드를 쓴다.
+
+그래서 세 가지를 여기 한 곳에 둔다:
+- 판정 `is_bdp_platform()` — `HDSP_ENV` 가 dev/prod 면 사내다. `CODEBUFF_BDP_RULES=1/0` 이 우선한다
+  (로컬에서 켜 보거나, 운영에서 문구가 틀렸을 때 재배포 없이 끄는 스위치).
+- 규칙 텍스트 `platform_rules_block()` — 지시문에 붙인다. 사내가 아니면 빈 문자열이라
+  로컬 동작은 한 글자도 안 바뀐다. centri 키 `prompts.bdp_platform_rules`(이슈 #178), 없으면
+  `~/.codebuff/bdp_rules.md` 가 내장 텍스트를 대체한다.
+- 가드 `tool_call_violation()` — 도구 인자에서 boto3 직접 사용을 찾아 bdpengine 안내를 돌려준다.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Any, Dict, Optional
+
+BDP_RULES_ENV = "CODEBUFF_BDP_RULES"
+BDP_RULES_PATH = "~/.codebuff/bdp_rules.md"
+
+_PLATFORM_ENVS = ("dev", "prod")
+
+#: 내장 규칙 문구는 스냅샷 `prompts.bdp_platform_rules` 다 (이슈 #218 — 코드 상수 없음).
+#: 저장소에서 확인된 bdpengine 함수는 `start_query`·`get_boto3_client` 둘뿐이다
+#: (`secrets_bootstrap.py`, `http_handlers.py`, `mock_packages/bdpengine`). 나머지는 지어내지
+#: 않고 모델이 직접 확인하게 한다. 사내 관리자는 `~/.codebuff/bdp_rules.md` 로 바꾼다.
+
+BDP_GUARD_MESSAGE = (
+    "이 환경(HDSP 노트북)에서는 boto3 를 직접 쓸 수 없습니다 (감지: `{line}`). "
+    "`from bdpengine.functions import ...` 로 다시 작성하세요 — Athena 는 "
+    "`start_query(query=...)`, AWS 클라이언트가 필요하면 `get_boto3_client('<service>')`."
+)
+
+# 코드: 줄 머리의 import 와 클라이언트 직접 생성. `get_boto3_client` 는 `_` 가 단어 문자라
+# `\bboto3` 경계가 서지 않아 걸리지 않는다.
+_CODE_IMPORT = re.compile(r"^\s*(?:import|from)\s+boto3\b")
+_CLIENT_CALL = re.compile(r"\bboto3\.(?:client|resource|Session|session)\s*\(")
+# 셸: `python -c "import boto3"` 처럼 import 가 줄 가운데 온다.
+_SHELL_IMPORT = re.compile(r"\b(?:import|from)\s+boto3\b")
+# 검색은 실행이 아니다 — `grep "import boto3"` 는 boto3 를 옮기는 작업의 첫 수다.
+_SHELL_SEARCH = re.compile(r"^\s*(?:grep|egrep|rg|ag|ack|git\s+grep)\b")
+_SWITCH_ON = ("1", "true", "yes", "on")
+_SWITCH_OFF = ("0", "false", "no", "off")
+_MAX_REPORTED = 200
+
+#: 도구 이름 → (코드가 실리는 인자, 셸 명령인가). 두 엔진의 쓰기·실행 도구를 다 적는다
+#: — codex: write_file·edit_file·execute_command, client: jupyter_cell·file_write·write_file·edit_file.
+_TOOL_CODE_FIELDS = {
+    "write_file": ("content", False),
+    "edit_file": ("new_string", False),
+    "execute_command": ("command", True),
+    "jupyter_cell": ("code", False),
+    "file_write": ("content", False),
+}
+
+
+def is_bdp_platform() -> bool:
+    switch = os.environ.get(BDP_RULES_ENV, "").strip().lower()
+    if switch in _SWITCH_ON or switch in _SWITCH_OFF:
+        return switch in _SWITCH_ON
+    return os.environ.get("HDSP_ENV", "").strip().lower() in _PLATFORM_ENVS
+
+
+def platform_rules_block() -> str:
+    """사내면 지시문에 붙일 규칙, 아니면 빈 문자열.
+
+    문구는 centri 키 `prompts.bdp_platform_rules` > `~/.codebuff/bdp_rules.md` > 스냅샷 기본값
+    순이다 (이슈 #178, #218). 키는 문구만 바꾼다 — 사내가 아니면 키가 있어도 붙이지 않는다.
+    """
+    if not is_bdp_platform():
+        return ""
+    from codebuff_core.managers.config_manager import configured_prompt
+
+    configured = configured_prompt("bdp_platform_rules")
+    if configured:
+        return configured
+    try:
+        with open(os.path.expanduser(BDP_RULES_PATH), encoding="utf-8") as f:
+            custom = f.read().strip()
+        if custom:
+            return custom
+    except (OSError, UnicodeDecodeError):
+        # 관리자 파일 하나가 두 엔진의 시작을 막지 않게 내장 문구로 돌아간다
+        pass
+    from codebuff_core.managers.remote_config import snapshot_prompt
+
+    return snapshot_prompt("bdp_platform_rules")
+
+
+def find_direct_boto3(text: str, shell: bool = False) -> Optional[str]:
+    """boto3 를 직접 쓰는 첫 줄(최대 200자)을 돌려준다. 없으면 None.
+
+    `#` 뒤 주석은 보지 않는다. 문자열·docstring 안의 `boto3.client(` 는 잡는다(오탐).
+    `import os, boto3` 처럼 줄 머리가 아닌 import 는 못 잡는다(미탐) — 앵커를 풀면
+    주석·문자열 오탐이 늘어서 이쪽을 택했다. 한계는 테스트가 고정한다.
+    """
+    imports = _SHELL_IMPORT if shell else _CODE_IMPORT
+    for line in (text or "").splitlines():
+        code = line.split("#", 1)[0]
+        if not code.strip() or (shell and _SHELL_SEARCH.search(code)):
+            continue
+        if imports.search(code) or _CLIENT_CALL.search(code):
+            return line.strip()[:_MAX_REPORTED]
+    return None
+
+
+def tool_call_violation(tool_name: str, args: Dict[str, Any]) -> Optional[str]:
+    """사내에서 도구 인자가 boto3 를 직접 쓰면 모델에 돌려줄 오류 문구, 아니면 None."""
+    field = _TOOL_CODE_FIELDS.get(tool_name)
+    if field is None or not is_bdp_platform():
+        return None
+    key, shell = field
+    value = (args or {}).get(key)
+    if not isinstance(value, str):
+        return None
+    line = find_direct_boto3(value, shell=shell)
+    return BDP_GUARD_MESSAGE.format(line=line) if line else None
+
+
+def with_platform_rules(prompt: str) -> str:
+    """사내면 프롬프트 뒤에 규칙을 붙인다. 아니면 그대로 돌려준다."""
+    rules = platform_rules_block()
+    return prompt + "\n\n" + rules if rules else prompt

codebuff_core/prompts/__init__.py

@@ -0,0 +1,44 @@
+"""
+Codebuff Core - Prompts
+
+Prompt templates for Auto-Agent.
+"""
+
+from .auto_agent_prompts import (
+    ADAPTIVE_REPLAN_PROMPT,
+    CODE_GENERATION_PROMPT,
+    ERROR_ANALYSIS_PROMPT,
+    ERROR_REFINEMENT_PROMPT,
+    FINAL_ANSWER_PROMPT,
+    PIP_INDEX_OPTION,
+    PLAN_GENERATION_PROMPT,
+    REFLECTION_PROMPT,
+    STRUCTURED_PLAN_PROMPT,
+    format_error_analysis_prompt,
+    format_final_answer_prompt,
+    format_plan_prompt,
+    format_refine_prompt,
+    format_reflection_prompt,
+    format_replan_prompt,
+    format_structured_plan_prompt,
+)
+
+__all__ = [
+    # Auto-Agent Prompts
+    "PLAN_GENERATION_PROMPT",
+    "CODE_GENERATION_PROMPT",
+    "ERROR_REFINEMENT_PROMPT",
+    "ADAPTIVE_REPLAN_PROMPT",
+    "STRUCTURED_PLAN_PROMPT",
+    "REFLECTION_PROMPT",
+    "FINAL_ANSWER_PROMPT",
+    "ERROR_ANALYSIS_PROMPT",
+    "PIP_INDEX_OPTION",
+    "format_plan_prompt",
+    "format_refine_prompt",
+    "format_final_answer_prompt",
+    "format_replan_prompt",
+    "format_structured_plan_prompt",
+    "format_reflection_prompt",
+    "format_error_analysis_prompt",
+]