hdsp-jupyter-extension 2.0.0__py3-none-any.whl

agent_server/routers/rag.py

@@ -0,0 +1,163 @@
+"""
+RAG Router - Endpoints for RAG search and status.
+
+Provides:
+- POST /rag/search - Explicit RAG search
+- GET /rag/status - RAG system status
+- POST /rag/reindex - Manual re-indexing trigger
+"""
+
+import logging
+
+from fastapi import APIRouter, HTTPException
+from hdsp_agent_core.models.rag import (
+    ChunkDebugInfo,
+    DebugSearchRequest,
+    DebugSearchResponse,
+    IndexStatusResponse,
+    LibraryDetectionDebug,
+    ReindexRequest,
+    ReindexResponse,
+    SearchConfigDebug,
+    SearchRequest,
+    SearchResponse,
+    SearchResult,
+)
+
+from agent_server.core.rag_manager import get_rag_manager
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@router.post("/search", response_model=SearchResponse)
+async def search(request: SearchRequest) -> SearchResponse:
+    """
+    Perform explicit RAG search.
+
+    Use this endpoint for direct knowledge base queries.
+    For automatic RAG context in plan generation, use /agent/plan instead.
+    """
+    rag_manager = get_rag_manager()
+
+    if not rag_manager.is_ready:
+        raise HTTPException(
+            status_code=503,
+            detail="RAG system not ready. Check /rag/status for details.",
+        )
+
+    try:
+        results = await rag_manager.search(
+            query=request.query, top_k=request.top_k, filters=request.filters
+        )
+
+        search_results = [
+            SearchResult(
+                content=r["content"],
+                score=r["score"] if request.include_score else 0.0,
+                metadata=r["metadata"],
+            )
+            for r in results
+        ]
+
+        return SearchResponse(
+            results=search_results,
+            query=request.query,
+            total_results=len(search_results),
+        )
+
+    except Exception as e:
+        logger.error(f"Search failed: {e}")
+        raise HTTPException(status_code=500, detail=f"Search failed: {str(e)}")
+
+
+@router.get("/status", response_model=IndexStatusResponse)
+async def get_status() -> IndexStatusResponse:
+    """
+    Get RAG system status.
+
+    Returns information about:
+    - System readiness
+    - Document/chunk counts
+    - Last update time
+    - Knowledge base path
+    """
+    rag_manager = get_rag_manager()
+    return rag_manager.get_status()
+
+
+@router.post("/reindex", response_model=ReindexResponse)
+async def reindex(request: ReindexRequest) -> ReindexResponse:
+    """
+    Manually trigger re-indexing.
+
+    Use this to:
+    - Force full reindex after knowledge base changes
+    - Index a specific file or directory
+    """
+    rag_manager = get_rag_manager()
+
+    if not rag_manager.is_ready:
+        raise HTTPException(
+            status_code=503,
+            detail="RAG system not ready. Check /rag/status for details.",
+        )
+
+    try:
+        # For now, return a simple success response
+        # Full reindex implementation would go here
+        return ReindexResponse(success=True, indexed=0, skipped=0, errors=[])
+
+    except Exception as e:
+        logger.error(f"Reindex failed: {e}")
+        raise HTTPException(status_code=500, detail=f"Reindex failed: {str(e)}")
+
+
+@router.post("/debug", response_model=DebugSearchResponse)
+async def debug_search(request: DebugSearchRequest) -> DebugSearchResponse:
+    """
+    RAG 검색 디버깅 - 전체 파이프라인 리니지 추적.
+
+    사용 사례:
+    - 특정 청크가 왜 검색되었는지 확인
+    - 점수 계산이 최종 RAG 컨텍스트에 어떻게 영향을 미치는지 분석
+
+    반환 정보:
+    - 라이브러리 감지 결과
+    - 청크별 벡터 유사도 점수
+    - 최종 포맷된 컨텍스트
+    """
+    rag_manager = get_rag_manager()
+
+    if not rag_manager.is_ready:
+        raise HTTPException(
+            status_code=503,
+            detail="RAG system not ready. Check /rag/status for details.",
+        )
+
+    try:
+        result = await rag_manager.debug_search(
+            query=request.query,
+            imported_libraries=request.imported_libraries,
+            top_k=request.top_k,
+            include_full_content=request.include_full_content,
+            simulate_plan_context=request.simulate_plan_context,
+        )
+
+        # Convert dict to response model
+        return DebugSearchResponse(
+            library_detection=LibraryDetectionDebug(**result["library_detection"]),
+            config=SearchConfigDebug(**result["config"]),
+            chunks=[ChunkDebugInfo(**c) for c in result["chunks"]],
+            total_candidates=result["total_candidates"],
+            total_passed_threshold=result["total_passed_threshold"],
+            search_ms=result["search_ms"],
+            formatted_context=result["formatted_context"],
+            context_char_count=result["context_char_count"],
+            estimated_context_tokens=result["estimated_context_tokens"],
+        )
+
+    except Exception as e:
+        logger.error(f"Debug search failed: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Debug search failed: {str(e)}")

agent_server/schemas/__init__.py

@@ -0,0 +1,60 @@
+"""
+Agent Server API Schemas
+
+Re-export from hdsp_agent_core.models for backward compatibility.
+"""
+
+from hdsp_agent_core.models.agent import (
+    ExecutionPlan,
+    PlanRequest,
+    PlanResponse,
+    PlanStep,
+    RefineRequest,
+    RefineResponse,
+    ReflectRequest,
+    ReflectResponse,
+    ReplanRequest,
+    ReplanResponse,
+    ReportExecutionRequest,
+    ReportExecutionResponse,
+    VerifyStateRequest,
+    VerifyStateResponse,
+)
+from hdsp_agent_core.models.chat import (
+    ChatRequest,
+    ChatResponse,
+    StreamChunk,
+)
+from hdsp_agent_core.models.common import (
+    APIResponse,
+    ErrorInfo,
+    NotebookContext,
+    ToolCall,
+)
+
+__all__ = [
+    # Common
+    "APIResponse",
+    "ErrorInfo",
+    "NotebookContext",
+    "ToolCall",
+    # Agent
+    "ExecutionPlan",
+    "PlanRequest",
+    "PlanResponse",
+    "PlanStep",
+    "RefineRequest",
+    "RefineResponse",
+    "ReflectRequest",
+    "ReflectResponse",
+    "ReplanRequest",
+    "ReplanResponse",
+    "ReportExecutionRequest",
+    "ReportExecutionResponse",
+    "VerifyStateRequest",
+    "VerifyStateResponse",
+    # Chat
+    "ChatRequest",
+    "ChatResponse",
+    "StreamChunk",
+]

hdsp_agent_core/__init__.py

@@ -0,0 +1,158 @@
+"""
+HDSP Agent Core - Shared Core Library
+
+Embedded Agent Server Architecture를 위한 공유 코어 라이브러리.
+Development(embedded)와 Production(proxy) 모드 모두에서 사용되는 공통 컴포넌트.
+
+Modules:
+- models: Pydantic data models (agent, chat, common, rag)
+- managers: Singleton managers (config, session, rag)
+- llm: LLM service abstraction (multi-provider support)
+- knowledge: Knowledge base and document chunking
+- prompts: Prompt templates for Auto-Agent
+"""
+
+__version__ = "1.0.0"
+
+# Models
+from hdsp_agent_core.models import (
+    # Common
+    APIResponse,
+    ErrorInfo,
+    GeminiConfig,
+    LLMConfig,
+    NotebookContext,
+    OpenAIConfig,
+    ToolCall,
+    VLLMConfig,
+    # Agent
+    ExecutionPlan,
+    PlanRequest,
+    PlanResponse,
+    PlanStep,
+    RefineRequest,
+    RefineResponse,
+    ReplanRequest,
+    ReplanResponse,
+    ValidationIssue,
+    # Chat
+    ChatRequest,
+    ChatResponse,
+    StreamChunk,
+    # RAG
+    ChunkingConfig,
+    EmbeddingConfig,
+    IndexStatusResponse,
+    QdrantConfig,
+    RAGConfig,
+    ReindexRequest,
+    ReindexResponse,
+    SearchRequest,
+    SearchResponse,
+    WatchdogConfig,
+)
+
+# Managers
+from hdsp_agent_core.managers import (
+    ConfigManager,
+    SessionManager,
+    get_config_manager,
+    get_session_manager,
+)
+
+# LLM
+from hdsp_agent_core.llm import (
+    LLMService,
+    call_llm,
+    call_llm_stream,
+)
+
+# Knowledge
+from hdsp_agent_core.knowledge import (
+    DocumentChunker,
+    KnowledgeBase,
+    KnowledgeLoader,
+    LibraryDetector,
+    chunk_file,
+    get_knowledge_base,
+    get_knowledge_loader,
+    get_library_detector,
+    LIBRARY_DESCRIPTIONS,
+)
+
+# Prompts
+from hdsp_agent_core.prompts import (
+    PLAN_GENERATION_PROMPT,
+    CODE_GENERATION_PROMPT,
+    ERROR_REFINEMENT_PROMPT,
+    ADAPTIVE_REPLAN_PROMPT,
+    format_plan_prompt,
+    format_refine_prompt,
+    format_replan_prompt,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Models - Common
+    "APIResponse",
+    "ErrorInfo",
+    "GeminiConfig",
+    "LLMConfig",
+    "NotebookContext",
+    "OpenAIConfig",
+    "ToolCall",
+    "VLLMConfig",
+    # Models - Agent
+    "ExecutionPlan",
+    "PlanRequest",
+    "PlanResponse",
+    "PlanStep",
+    "RefineRequest",
+    "RefineResponse",
+    "ReplanRequest",
+    "ReplanResponse",
+    "ValidationIssue",
+    # Models - Chat
+    "ChatRequest",
+    "ChatResponse",
+    "StreamChunk",
+    # Models - RAG
+    "ChunkingConfig",
+    "EmbeddingConfig",
+    "IndexStatusResponse",
+    "QdrantConfig",
+    "RAGConfig",
+    "ReindexRequest",
+    "ReindexResponse",
+    "SearchRequest",
+    "SearchResponse",
+    "WatchdogConfig",
+    # Managers
+    "ConfigManager",
+    "SessionManager",
+    "get_config_manager",
+    "get_session_manager",
+    # LLM
+    "LLMService",
+    "call_llm",
+    "call_llm_stream",
+    # Knowledge
+    "DocumentChunker",
+    "KnowledgeBase",
+    "KnowledgeLoader",
+    "LibraryDetector",
+    "chunk_file",
+    "get_knowledge_base",
+    "get_knowledge_loader",
+    "get_library_detector",
+    "LIBRARY_DESCRIPTIONS",
+    # Prompts
+    "PLAN_GENERATION_PROMPT",
+    "CODE_GENERATION_PROMPT",
+    "ERROR_REFINEMENT_PROMPT",
+    "ADAPTIVE_REPLAN_PROMPT",
+    "format_plan_prompt",
+    "format_refine_prompt",
+    "format_replan_prompt",
+]

hdsp_agent_core/factory.py

@@ -0,0 +1,252 @@
+"""
+HDSP Agent Core - Service Factory
+
+ServiceFactory for creating Embedded or Proxy service implementations
+based on the HDSP_AGENT_MODE environment variable.
+
+Modes:
+- embedded: Services run directly in-process (development mode)
+- proxy: Services proxy to external agent server via HTTP (production mode)
+"""
+
+import logging
+import os
+from enum import Enum
+from typing import Optional
+
+from hdsp_agent_core.interfaces import IAgentService, IChatService, IRAGService
+
+logger = logging.getLogger(__name__)
+
+
+class AgentMode(Enum):
+    """Agent execution mode"""
+    EMBEDDED = "embedded"  # Direct in-process execution
+    PROXY = "proxy"        # HTTP proxy to external server
+
+
+class ServiceFactory:
+    """
+    Factory for creating service instances based on execution mode.
+
+    Singleton pattern ensures consistent service instances across the application.
+
+    Usage:
+        factory = ServiceFactory.get_instance()
+        await factory.initialize()
+
+        agent_service = factory.get_agent_service()
+        chat_service = factory.get_chat_service()
+        rag_service = factory.get_rag_service()
+
+    Environment Variables:
+        HDSP_AGENT_MODE: "embedded" or "proxy" (default: "proxy")
+        AGENT_SERVER_URL: URL for proxy mode (default: "http://localhost:8000")
+        AGENT_SERVER_TIMEOUT: HTTP timeout in seconds (default: 120.0)
+    """
+
+    _instance: Optional["ServiceFactory"] = None
+
+    def __init__(self):
+        """Initialize factory (use get_instance() instead)"""
+        self._mode = self._detect_mode()
+        self._initialized = False
+
+        # Service instances (lazy loaded)
+        self._agent_service: Optional[IAgentService] = None
+        self._chat_service: Optional[IChatService] = None
+        self._rag_service: Optional[IRAGService] = None
+
+        # Proxy configuration
+        self._server_url = os.environ.get("AGENT_SERVER_URL", "http://localhost:8000")
+        self._timeout = float(os.environ.get("AGENT_SERVER_TIMEOUT", "120.0"))
+
+        logger.info(f"ServiceFactory created with mode: {self._mode.value}")
+
+    @classmethod
+    def get_instance(cls) -> "ServiceFactory":
+        """Get singleton factory instance"""
+        if cls._instance is None:
+            cls._instance = ServiceFactory()
+        return cls._instance
+
+    @classmethod
+    def reset_instance(cls) -> None:
+        """Reset singleton instance (for testing)"""
+        cls._instance = None
+
+    def _detect_mode(self) -> AgentMode:
+        """Detect execution mode from environment variable"""
+        mode_str = os.environ.get("HDSP_AGENT_MODE", "proxy").lower()
+
+        if mode_str == "embedded":
+            return AgentMode.EMBEDDED
+        elif mode_str == "proxy":
+            return AgentMode.PROXY
+        else:
+            logger.warning(
+                f"Unknown HDSP_AGENT_MODE '{mode_str}', defaulting to proxy"
+            )
+            return AgentMode.PROXY
+
+    @property
+    def mode(self) -> AgentMode:
+        """Get current execution mode"""
+        return self._mode
+
+    @property
+    def is_embedded(self) -> bool:
+        """Check if running in embedded mode"""
+        return self._mode == AgentMode.EMBEDDED
+
+    @property
+    def is_proxy(self) -> bool:
+        """Check if running in proxy mode"""
+        return self._mode == AgentMode.PROXY
+
+    @property
+    def is_initialized(self) -> bool:
+        """Check if factory has been initialized"""
+        return self._initialized
+
+    @property
+    def server_url(self) -> str:
+        """Get agent server URL (for proxy mode)"""
+        return self._server_url
+
+    @property
+    def timeout(self) -> float:
+        """Get HTTP timeout (for proxy mode)"""
+        return self._timeout
+
+    async def initialize(self) -> None:
+        """
+        Initialize all services based on current mode.
+
+        For embedded mode: Initializes RAG manager, loads knowledge base
+        For proxy mode: Validates server connectivity
+        """
+        if self._initialized:
+            logger.debug("ServiceFactory already initialized")
+            return
+
+        logger.info(f"Initializing ServiceFactory in {self._mode.value} mode")
+
+        if self.is_embedded:
+            await self._initialize_embedded_services()
+        else:
+            await self._initialize_proxy_services()
+
+        self._initialized = True
+        logger.info(f"ServiceFactory initialization complete ({self._mode.value} mode)")
+
+    async def _initialize_embedded_services(self) -> None:
+        """Initialize services for embedded mode"""
+        from hdsp_agent_core.services.agent_service import EmbeddedAgentService
+        from hdsp_agent_core.services.chat_service import EmbeddedChatService
+        from hdsp_agent_core.services.rag_service import EmbeddedRAGService
+
+        # Create service instances
+        self._agent_service = EmbeddedAgentService()
+        self._chat_service = EmbeddedChatService()
+        self._rag_service = EmbeddedRAGService()
+
+        # Initialize RAG service (may need async initialization)
+        await self._rag_service.initialize()
+
+        logger.info("Embedded services initialized")
+
+    async def _initialize_proxy_services(self) -> None:
+        """Initialize services for proxy mode"""
+        from hdsp_agent_core.services.agent_service import ProxyAgentService
+        from hdsp_agent_core.services.chat_service import ProxyChatService
+        from hdsp_agent_core.services.rag_service import ProxyRAGService
+
+        # Create proxy service instances
+        self._agent_service = ProxyAgentService(
+            base_url=self._server_url,
+            timeout=self._timeout
+        )
+        self._chat_service = ProxyChatService(
+            base_url=self._server_url,
+            timeout=self._timeout
+        )
+        self._rag_service = ProxyRAGService(
+            base_url=self._server_url,
+            timeout=self._timeout
+        )
+
+        # Optionally validate connectivity
+        # await self._validate_server_connectivity()
+
+        logger.info(f"Proxy services initialized (server: {self._server_url})")
+
+    async def shutdown(self) -> None:
+        """Shutdown all services and cleanup resources"""
+        logger.info("Shutting down ServiceFactory")
+
+        # Cleanup RAG service
+        if self._rag_service and hasattr(self._rag_service, "shutdown"):
+            await self._rag_service.shutdown()
+
+        # Reset service instances
+        self._agent_service = None
+        self._chat_service = None
+        self._rag_service = None
+        self._initialized = False
+
+        logger.info("ServiceFactory shutdown complete")
+
+    def get_agent_service(self) -> IAgentService:
+        """
+        Get the Agent service instance.
+
+        Returns:
+            IAgentService implementation based on current mode
+
+        Raises:
+            RuntimeError: If factory not initialized
+        """
+        if not self._initialized:
+            raise RuntimeError(
+                "ServiceFactory not initialized. Call await factory.initialize() first."
+            )
+        return self._agent_service
+
+    def get_chat_service(self) -> IChatService:
+        """
+        Get the Chat service instance.
+
+        Returns:
+            IChatService implementation based on current mode
+
+        Raises:
+            RuntimeError: If factory not initialized
+        """
+        if not self._initialized:
+            raise RuntimeError(
+                "ServiceFactory not initialized. Call await factory.initialize() first."
+            )
+        return self._chat_service
+
+    def get_rag_service(self) -> IRAGService:
+        """
+        Get the RAG service instance.
+
+        Returns:
+            IRAGService implementation based on current mode
+
+        Raises:
+            RuntimeError: If factory not initialized
+        """
+        if not self._initialized:
+            raise RuntimeError(
+                "ServiceFactory not initialized. Call await factory.initialize() first."
+            )
+        return self._rag_service
+
+
+# Convenience function for getting the singleton factory
+def get_service_factory() -> ServiceFactory:
+    """Get the singleton ServiceFactory instance"""
+    return ServiceFactory.get_instance()