contextual-engine 0.1.0__py3-none-any.whl

contextual/core/__init__.py

@@ -0,0 +1,11 @@
+"""Core data models, errors, and orchestration engine.
+
+This module contains the foundational contracts that all other modules depend on.
+All data shapes (Pydantic models), error types, and the main indexing/retrieval
+orchestrator live here.
+"""
+from __future__ import annotations
+
+
+__all__ = []
+# Exports will be added as models.py, errors.py, and engine.py are built

contextual/core/errors.py

@@ -0,0 +1,470 @@
+"""Error types and exception hierarchy for Contextual.
+
+Provides typed error codes and structured exceptions for consistent error handling
+across all modules. Every error carries a code, message, and optional context.
+
+Error handling philosophy:
+- Fail fast with clear error messages
+- Never swallow exceptions silently
+- Provide actionable error context
+- Distinguish retriable vs non-retriable errors
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+
+# ============================================================================
+# ERROR CODES - Typed categorical error classification
+# ============================================================================
+
+
+class ErrorCode(StrEnum):
+    """Categorized error codes for all subsystems.
+
+    Format: SUBSYSTEM_SPECIFIC_CONDITION
+
+    These codes enable:
+    - Structured error logging
+    - Client-side error handling (MCP clients)
+    - Metrics/alerting aggregation
+    - Automatic retry logic
+    """
+
+    # ========================================================================
+    # STORAGE ERRORS (1xx range conceptually)
+    # ========================================================================
+
+    # SQLite errors
+    STORAGE_SQLITE_CONNECTION_FAILED = "storage_sqlite_connection_failed"
+    STORAGE_SQLITE_POOL_EXHAUSTED = "storage_sqlite_pool_exhausted"
+    STORAGE_SQLITE_QUERY_FAILED = "storage_sqlite_query_failed"
+    STORAGE_SQLITE_TRANSACTION_FAILED = "storage_sqlite_transaction_failed"
+    STORAGE_SQLITE_SCHEMA_INVALID = "storage_sqlite_schema_invalid"
+    STORAGE_SQLITE_WAL_CHECKPOINT_FAILED = "storage_sqlite_wal_checkpoint_failed"
+    STORAGE_SQLITE_BUSY = "storage_sqlite_busy"  # Retriable
+
+    # LanceDB errors
+    STORAGE_LANCE_CONNECTION_FAILED = "storage_lance_connection_failed"
+    STORAGE_LANCE_TABLE_NOT_FOUND = "storage_lance_table_not_found"
+    STORAGE_LANCE_INSERT_FAILED = "storage_lance_insert_failed"
+    STORAGE_LANCE_SEARCH_FAILED = "storage_lance_search_failed"
+    STORAGE_LANCE_INDEX_FAILED = "storage_lance_index_failed"
+    STORAGE_LANCE_OPTIMIZE_FAILED = "storage_lance_optimize_failed"
+
+    # Vec0 errors
+    STORAGE_VEC_FAILED = "storage_vec_failed"
+    STORAGE_VEC_DIMENSION_MISMATCH = "storage_vec_dimension_mismatch"
+    STORAGE_VEC_INVALID_PARAMETER = "storage_vec_invalid_parameter"
+
+    # Tantivy errors
+    STORAGE_TANTIVY_INDEX_OPEN_FAILED = "storage_tantivy_index_open_failed"
+    STORAGE_TANTIVY_INDEX_WRITE_FAILED = "storage_tantivy_index_write_failed"
+    STORAGE_TANTIVY_SEARCH_FAILED = "storage_tantivy_search_failed"
+
+    # Migration errors
+    STORAGE_MIGRATION_FAILED = "storage_migration_failed"
+    STORAGE_MIGRATION_ROLLBACK_FAILED = "storage_migration_rollback_failed"
+    STORAGE_MIGRATION_VERSION_CONFLICT = "storage_migration_version_conflict"
+
+    # Temporal query errors
+    STORAGE_TEMPORAL_QUERY_INVALID = "storage_temporal_query_invalid"
+    STORAGE_TEMPORAL_CONTRADICTION_DETECTED = "storage_temporal_contradiction_detected"
+
+    # ========================================================================
+    # INDEXING ERRORS (2xx range conceptually)
+    # ========================================================================
+
+    # Parser errors
+    INDEXING_PARSER_INIT_FAILED = "indexing_parser_init_failed"
+    INDEXING_PARSER_PARSE_FAILED = "indexing_parser_parse_failed"
+    INDEXING_PARSER_UNSUPPORTED_LANGUAGE = "indexing_parser_unsupported_language"
+    INDEXING_PARSER_POOL_EXHAUSTED = "indexing_parser_pool_exhausted"
+
+    # Chunking errors
+    INDEXING_CHUNKER_FILE_TOO_LARGE = "indexing_chunker_file_too_large"
+    INDEXING_CHUNKER_BINARY_FILE = "indexing_chunker_binary_file"
+    INDEXING_CHUNKER_ENCODING_ERROR = "indexing_chunker_encoding_error"
+    INDEXING_CHUNKER_SPLIT_FAILED = "indexing_chunker_split_failed"
+
+    # File processing errors
+    INDEXING_FILE_NOT_FOUND = "indexing_file_not_found"
+    INDEXING_FILE_PERMISSION_DENIED = "indexing_file_permission_denied"
+    INDEXING_FILE_READ_FAILED = "indexing_file_read_failed"
+    INDEXING_FILE_IGNORED = "indexing_file_ignored"  # Not an error, just logged
+
+    # Embedding errors
+    INDEXING_EMBEDDING_MODEL_LOAD_FAILED = "indexing_embedding_model_load_failed"
+    INDEXING_EMBEDDING_INFERENCE_FAILED = "indexing_embedding_inference_failed"
+    INDEXING_EMBEDDING_BATCH_TOO_LARGE = "indexing_embedding_batch_too_large"
+    INDEXING_EMBEDDING_OOM = "indexing_embedding_oom"  # Out of memory
+
+    # Content hash errors
+    INDEXING_HASH_COLLISION = "indexing_hash_collision"  # Extremely unlikely SHA-256 collision
+
+    # ========================================================================
+    # GIT ERRORS (3xx range conceptually)
+    # ========================================================================
+
+    GIT_REPO_NOT_FOUND = "git_repo_not_found"
+    GIT_REPO_INVALID = "git_repo_invalid"
+    GIT_COMMIT_WALK_FAILED = "git_commit_walk_failed"
+    GIT_BLAME_FAILED = "git_blame_failed"
+    GIT_DIFF_FAILED = "git_diff_failed"
+    GIT_SHALLOW_CLONE = "git_shallow_clone"  # Warning, not error
+    GIT_DETACHED_HEAD = "git_detached_head"  # Warning
+    GIT_REBASE_DETECTED = "git_rebase_detected"  # Requires special handling
+    GIT_FORCE_PUSH_DETECTED = "git_force_push_detected"  # Requires re-indexing
+
+    # ========================================================================
+    # RETRIEVAL ERRORS (4xx range conceptually)
+    # ========================================================================
+
+    # Search errors
+    RETRIEVAL_QUERY_EMPTY = "retrieval_query_empty"
+    RETRIEVAL_QUERY_TOO_LONG = "retrieval_query_too_long"
+    RETRIEVAL_BM25_FAILED = "retrieval_bm25_failed"
+    RETRIEVAL_DENSE_SEARCH_FAILED = "retrieval_dense_search_failed"
+    RETRIEVAL_FUSION_FAILED = "retrieval_fusion_failed"
+    RETRIEVAL_RERANK_FAILED = "retrieval_rerank_failed"
+    RETRIEVAL_HYDRATION_FAILED = "retrieval_hydration_failed"
+    RETRIEVAL_NO_RESULTS = "retrieval_no_results"  # Not an error, informational
+
+    # Context assembly errors
+    RETRIEVAL_CONTEXT_BUDGET_EXCEEDED = "retrieval_context_budget_exceeded"
+    RETRIEVAL_CONTEXT_ASSEMBLY_FAILED = "retrieval_context_assembly_failed"
+
+    # ========================================================================
+    # SECURITY ERRORS (5xx range conceptually)
+    # ========================================================================
+
+    # Path safety errors
+    SECURITY_PATH_TRAVERSAL = "security_path_traversal"
+    SECURITY_PATH_OUTSIDE_ROOT = "security_path_outside_root"
+    SECURITY_PATH_SYMLINK_LOOP = "security_path_symlink_loop"
+    SECURITY_PATH_INVALID = "security_path_invalid"
+    SECURITY_PATH_RESERVED_NAME = "security_path_reserved_name"  # Windows: CON, PRN, etc.
+
+    # Sanitization errors
+    SECURITY_SQL_INJECTION_ATTEMPT = "security_sql_injection_attempt"
+    SECURITY_FTS5_INJECTION_ATTEMPT = "security_fts5_injection_attempt"
+    SECURITY_UNICODE_ATTACK = "security_unicode_attack"
+
+    # Workspace errors
+    SECURITY_WORKSPACE_PERMISSION_DENIED = "security_workspace_permission_denied"
+    SECURITY_WORKSPACE_INIT_FAILED = "security_workspace_init_failed"
+    SECURITY_WORKSPACE_ISOLATION_VIOLATION = "security_workspace_isolation_violation"
+
+    # Prompt injection
+    SECURITY_PROMPT_INJECTION_DETECTED = "security_prompt_injection_detected"
+
+    # ========================================================================
+    # CONFIGURATION ERRORS (6xx range conceptually)
+    # ========================================================================
+
+    CONFIG_FILE_NOT_FOUND = "config_file_not_found"
+    CONFIG_FILE_INVALID = "config_file_invalid"
+    CONFIG_PARSE_FAILED = "config_parse_failed"
+    CONFIG_VALIDATION_FAILED = "config_validation_failed"
+    CONFIG_MISSING_REQUIRED = "config_missing_required"
+    CONFIG_VALUE_OUT_OF_RANGE = "config_value_out_of_range"
+
+    # ========================================================================
+    # MCP SERVER ERRORS (7xx range conceptually)
+    # ========================================================================
+
+    MCP_TOOL_CALL_FAILED = "mcp_tool_call_failed"
+    MCP_INVALID_PARAMETERS = "mcp_invalid_parameters"
+    MCP_TRANSPORT_ERROR = "mcp_transport_error"
+    MCP_TIMEOUT = "mcp_timeout"
+    MCP_CLIENT_DISCONNECTED = "mcp_client_disconnected"
+
+    # ========================================================================
+    # SYSTEM ERRORS (8xx range conceptually)
+    # ========================================================================
+
+    SYSTEM_DISK_FULL = "system_disk_full"
+    SYSTEM_OOM = "system_oom"  # Out of memory
+    SYSTEM_PERMISSION_DENIED = "system_permission_denied"
+    SYSTEM_RESOURCE_EXHAUSTED = "system_resource_exhausted"
+    SYSTEM_SHUTDOWN = "system_shutdown"  # Graceful shutdown in progress
+
+    # ========================================================================
+    # UNKNOWN/INTERNAL ERRORS (9xx range conceptually)
+    # ========================================================================
+
+    INTERNAL_ASSERTION_FAILED = "internal_assertion_failed"
+    INTERNAL_INVARIANT_VIOLATED = "internal_invariant_violated"
+    INTERNAL_UNEXPECTED_STATE = "internal_unexpected_state"
+    UNKNOWN = "unknown"
+
+
+# ============================================================================
+# RETRY CLASSIFICATION
+# ============================================================================
+
+
+RETRIABLE_ERRORS = frozenset({
+    ErrorCode.STORAGE_SQLITE_BUSY,
+    ErrorCode.STORAGE_SQLITE_POOL_EXHAUSTED,
+    ErrorCode.INDEXING_PARSER_POOL_EXHAUSTED,
+    ErrorCode.INDEXING_EMBEDDING_OOM,
+    ErrorCode.MCP_TIMEOUT,
+    ErrorCode.MCP_CLIENT_DISCONNECTED,
+    ErrorCode.SYSTEM_RESOURCE_EXHAUSTED,
+})
+
+
+def is_retriable(code: ErrorCode) -> bool:
+    """Check if an error code represents a retriable condition.
+
+    Args:
+        code: Error code to check.
+
+    Returns:
+        True if the error should be retried, False otherwise.
+    """
+    return code in RETRIABLE_ERRORS
+
+
+# ============================================================================
+# EXCEPTION HIERARCHY
+# ============================================================================
+
+
+class ContextualExceptionError(Exception):
+    """Base exception for all Contextual errors.
+
+    All custom exceptions inherit from this to enable broad catch blocks
+    while maintaining error code granularity.
+
+    Attributes:
+        code: Typed error code for categorization.
+        message: Human-readable error message.
+        context: Additional error context (file paths, query text, etc.).
+    """
+
+    def __init__(
+        self,
+        code: ErrorCode,
+        message: str,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize a Contextual exception.
+
+        Args:
+            code: Error code categorizing this error.
+            message: Human-readable error description.
+            context: Optional contextual information.
+        """
+        self.code = code
+        self.message = message
+        self.context = context or {}
+        super().__init__(self._format_message())
+
+    def _format_message(self) -> str:
+        """Format the complete error message.
+
+        Returns:
+            Formatted message with code and context.
+        """
+        parts = [f"[{self.code.value}] {self.message}"]
+        if self.context:
+            context_str = ", ".join(f"{k}={v}" for k, v in self.context.items())
+            parts.append(f"({context_str})")
+        return " ".join(parts)
+
+    def is_retriable(self) -> bool:
+        """Check if this error represents a retriable condition.
+
+        Returns:
+            True if the error should be retried.
+        """
+        return is_retriable(self.code)
+
+
+# ============================================================================
+# SUBSYSTEM-SPECIFIC EXCEPTIONS
+# ============================================================================
+
+
+class StorageError(ContextualExceptionError):
+    """Errors from the storage layer (SQLite, LanceDB, tantivy)."""
+
+
+class IndexingError(ContextualExceptionError):
+    """Errors from the indexing pipeline (parsing, chunking, embedding)."""
+
+
+class GitError(ContextualExceptionError):
+    """Errors from git operations (commit walking, blame, diff)."""
+
+
+class RetrievalError(ContextualExceptionError):
+    """Errors from the retrieval pipeline (search, fusion, reranking)."""
+
+
+class SecurityError(ContextualExceptionError):
+    """Errors from security checks (path safety, sanitization, isolation)."""
+
+
+class ConfigError(ContextualExceptionError):
+    """Errors from configuration loading and validation."""
+
+
+class MCPError(ContextualExceptionError):
+    """Errors from MCP server operations."""
+
+
+class ContextualSystemError(ContextualExceptionError):
+    """System-level errors (disk, memory, permissions)."""
+
+
+class InternalError(ContextualExceptionError):
+    """Internal errors indicating bugs (assertion failures, invariant violations)."""
+
+
+# ============================================================================
+# ERROR CONTEXT HELPERS
+# ============================================================================
+
+
+def storage_context(
+    db_path: str | None = None,
+    table: str | None = None,
+    query: str | None = None,
+) -> dict[str, Any]:
+    """Build context dict for storage errors.
+
+    Args:
+        db_path: Database file path.
+        table: Table name.
+        query: SQL query (truncated if too long).
+
+    Returns:
+        Context dictionary.
+    """
+    context = {}
+    if db_path:
+        context["db_path"] = db_path
+    if table:
+        context["table"] = table
+    # Context truncation limit for long queries
+    _query_truncate_length = 200
+    if query:
+        # Truncate long queries
+        context["query"] = (
+            query[:_query_truncate_length] + "..."
+            if len(query) > _query_truncate_length
+            else query
+        )
+    return context
+
+
+def indexing_context(
+    file_path: str | None = None,
+    language: str | None = None,
+    line: int | None = None,
+) -> dict[str, Any]:
+    """Build context dict for indexing errors.
+
+    Args:
+        file_path: File being processed.
+        language: Programming language.
+        line: Line number where error occurred.
+
+    Returns:
+        Context dictionary.
+    """
+    context: dict[str, Any] = {}
+    if file_path:
+        context["file_path"] = file_path
+    if language:
+        context["language"] = language
+    if line is not None:
+        context["line"] = line
+    return context
+
+
+def git_context(
+    repo_path: str | None = None,
+    commit_sha: str | None = None,
+    branch: str | None = None,
+) -> dict[str, Any]:
+    """Build context dict for git errors.
+
+    Args:
+        repo_path: Repository path.
+        commit_sha: Commit SHA (first 8 chars).
+        branch: Branch name.
+
+    Returns:
+        Context dictionary.
+    """
+    context = {}
+    if repo_path:
+        context["repo_path"] = repo_path
+    if commit_sha:
+        context["commit_sha"] = commit_sha[:8]  # Short SHA
+    if branch:
+        context["branch"] = branch
+    return context
+
+
+def retrieval_context(
+    query: str | None = None,
+    top_k: int | None = None,
+    phase: str | None = None,
+) -> dict[str, Any]:
+    """Build context dict for retrieval errors.
+
+    Args:
+        query: Search query (truncated).
+        top_k: Number of results requested.
+        phase: Pipeline phase (bm25, dense, fusion, rerank).
+
+    Returns:
+        Context dictionary.
+    """
+    # Query truncation limit for retrieval context
+    _query_truncate_length = 100
+    context: dict[str, Any] = {}
+    if query:
+        # Truncate long queries
+        context["query"] = (
+            query[:_query_truncate_length] + "..."
+            if len(query) > _query_truncate_length
+            else query
+        )
+    if top_k is not None:
+        context["top_k"] = top_k
+    if phase:
+        context["phase"] = phase
+    return context
+
+
+def security_context(
+    path: str | None = None,
+    root: str | None = None,
+    attack_type: str | None = None,
+) -> dict[str, Any]:
+    """Build context dict for security errors.
+
+    Args:
+        path: Path that violated security check.
+        root: Expected root path.
+        attack_type: Type of attack detected.
+
+    Returns:
+        Context dictionary.
+    """
+    context = {}
+    if path:
+        context["path"] = path
+    if root:
+        context["root"] = root
+    if attack_type:
+        context["attack_type"] = attack_type
+    return context