feat: ClassifaiError class for Errors and logging

[frayle-ons]

✨ Summary

Package Level Error Handling

These changes add a custom error class, ClassifaiError used to catch and handle internal package errors, avoiding throwing raw errors or third party error message in code.

Additional subclasses of ClassifaiError are also introduced for specific workflows within the package code including:

• ConfigurationError
• DataValidationError
• ExternalServiceError
• VectorisationError
• IndexBuildError
• HookValidationError

The codebase for the Vectorisers, VectorStore and start_api functionality have also been updated to use these custom Error classes where needed.

Examples include:

• Trying to call a generative AI model API

        try:
            response = ollama.embed(model=self.model_name, input=texts)
        except Exception as e:
            raise ExternalServiceError(
                "Failed to generate embeddings using Ollama.",
                context={"vectoriser": "ollama", "model": self.model_name},
            ) from e

• Trying to execute a custom user hook and catching errors

        # ---- Preprocess hook -> HookError
        if "reverse_search_preprocess" in self.hooks:
            try:
                modified_query = self.hooks["reverse_search_preprocess"](query)
                query = VectorStoreReverseSearchInput.validate(modified_query)
            except Exception as e:
                raise HookError(
                    "reverse_search_preprocess hook raised an exception.",
                    context={"hook": "reverse_search_preprocess"},
                ) from e

FastAPI Level Error Handling

When running the fastapi restAPI server, it is not beneficial to return direct python error messaging to the endpoint in most cases. Instead, we can use custom exception handlers with FastAPI to handle errors. In these cases FastAPI allows us to map an error code to a specific HTML response and response code. Additionally, the FastAPI layer is still responsible for data validation using Pydantic model used to define the endpoint definitions.

📜 Changes Introduced

• feat: Added exceptions.py file to src directory which provides definition of ClassifaiError class
• feat Added error subclasses for different sections of the classifai workflow - hooks, data validation, external calls, etc
• refactor: Updated Vectoriser, Vectorstore and server logic to
• feat: Added exception handlers in fastapi code to handle new ClassifaiErrors thrown by internal code

✅ Checklist

Please confirm you've completed these checks before requesting a review.

• Code passes linting with Ruff
• Security checks pass using Bandit
• API and Unit tests are written and pass using pytest
• Terraform files (if applicable) follow best practices and have been validated (terraform fmt & terraform validate)
• DocStrings follow Google-style and are added as per Pylint recommendations
• Documentation has been updated if needed

🔍 How to Test