agent-learning-kit 0.1.0__py3-none-any.whl

fi/utils/errors.py

@@ -0,0 +1,200 @@
+"""Error hierarchy for the SDK.
+
+Trimmed to the classes actually referenced by ai-evaluation. If a new
+exception is needed, add it here instead of reaching back into a
+separate package.
+"""
+from collections.abc import Iterable
+from typing import List, Optional, Union
+
+from .constants import API_KEY_ENVVAR_NAME, SECRET_KEY_ENVVAR_NAME
+
+
+class SDKException(Exception):
+    """Base exception for all SDK errors."""
+
+    def __init__(self, message: Optional[str] = None, cause: Optional[Exception] = None) -> None:
+        self.custom_message = message
+        self.__cause__ = cause
+        super().__init__(message or self.get_message())
+
+    def __str__(self) -> str:
+        return self.custom_message or self.get_message()
+
+    def get_message(self) -> str:
+        if self.__cause__:
+            return f"An SDK error occurred, caused by: {self.__cause__}"
+        return "An unknown error occurred in the SDK."
+
+    def get_error_code(self) -> str:
+        return "UNKNOWN_SDK_ERROR"
+
+
+class MissingAuthError(SDKException):
+    def __init__(
+        self,
+        fi_api_key: Optional[str],
+        fi_secret_key: Optional[str],
+        cause: Optional[Exception] = None,
+    ) -> None:
+        self.missing_api_key = fi_api_key is None
+        self.missing_secret_key = fi_secret_key is None
+        super().__init__(cause=cause)
+
+    def get_message(self) -> str:
+        missing = []
+        if self.missing_api_key:
+            missing.append("'fi_api_key'")
+        if self.missing_secret_key:
+            missing.append("'fi_secret_key'")
+        return (
+            "FI Client could not obtain credentials. Pass fi_api_key and "
+            "fi_secret_key directly or set env vars:\n"
+            f" - {API_KEY_ENVVAR_NAME}\n"
+            f" - {SECRET_KEY_ENVVAR_NAME}\n"
+            f"Missing: {', '.join(missing)}"
+        )
+
+    def get_error_code(self) -> str:
+        return "MISSING_FI_CLIENT_AUTHENTICATION"
+
+
+class InvalidAuthError(SDKException):
+    """Raised when the api rejects credentials (bad/expired key)."""
+
+    def __init__(self, message: Optional[str] = None, cause: Optional[Exception] = None) -> None:
+        super().__init__(
+            message=message
+            or "Invalid FI Client Authentication, please check your API key and secret key.",
+            cause=cause,
+        )
+
+    def get_error_code(self) -> str:
+        return "INVALID_FI_CLIENT_AUTHENTICATION"
+
+
+class InvalidValueType(SDKException):
+    def __init__(
+        self,
+        value_name: str,
+        value: Union[bool, int, float, str],
+        correct_type: str,
+        cause: Optional[Exception] = None,
+    ) -> None:
+        self.value_name = value_name
+        self.value = value
+        self.correct_type = correct_type
+        super().__init__(cause=cause)
+
+    def get_message(self) -> str:
+        return (
+            f"{self.value_name} with value {self.value!r} is of type "
+            f"{type(self.value).__name__}, but expected from {self.correct_type}."
+        )
+
+    def get_error_code(self) -> str:
+        return "INVALID_VALUE_TYPE"
+
+
+class MissingRequiredKey(SDKException):
+    def __init__(self, field_name: str, missing_key: str, cause: Optional[Exception] = None) -> None:
+        self.field_name = field_name
+        self.missing_key = missing_key
+        super().__init__(
+            message=(
+                f"Missing required key '{missing_key}' in {field_name}. "
+                "Please check your configuration or API documentation."
+            ),
+            cause=cause,
+        )
+
+    def get_error_code(self) -> str:
+        return "MISSING_REQUIRED_KEY"
+
+
+class MissingRequiredConfigForEvalTemplate(SDKException):
+    def __init__(
+        self,
+        missing_key: str,
+        eval_template_name: str,
+        cause: Optional[Exception] = None,
+    ) -> None:
+        self.missing_key = missing_key
+        self.eval_template_name = eval_template_name
+        super().__init__(
+            message=(
+                f"Missing required config '{missing_key}' for eval template "
+                f"'{eval_template_name}'."
+            ),
+            cause=cause,
+        )
+
+    def get_error_code(self) -> str:
+        return "MISSING_EVAL_TEMPLATE_CONFIG"
+
+
+class InvalidAdditionalHeaders(SDKException):
+    def __init__(self, invalid_headers: Iterable, cause: Optional[Exception] = None) -> None:
+        self.invalid_header_names = invalid_headers
+        super().__init__(cause=cause)
+
+    def get_message(self) -> str:
+        return (
+            "Found invalid additional header, cannot use reserved headers named: "
+            f"{', '.join(map(str, self.invalid_header_names))}."
+        )
+
+    def get_error_code(self) -> str:
+        return "INVALID_ADDITIONAL_HEADERS"
+
+
+class DatasetNotFoundError(SDKException):
+    def __init__(self, message: Optional[str] = None, cause: Optional[Exception] = None) -> None:
+        super().__init__(
+            message=message or "No existing dataset found for current dataset name.",
+            cause=cause,
+        )
+
+    def get_error_code(self) -> str:
+        return "DATASET_NOT_FOUND"
+
+
+class FileNotFoundException(SDKException):
+    def __init__(
+        self,
+        file_path: Union[str, List[str]],
+        message: Optional[str] = None,
+        cause: Optional[Exception] = None,
+    ) -> None:
+        self.file_path = file_path
+        super().__init__(message=message or self._default_message(), cause=cause)
+
+    def _default_message(self) -> str:
+        if isinstance(self.file_path, list):
+            head = ", ".join(map(str, self.file_path[:3]))
+            if len(self.file_path) > 3:
+                head += f", and {len(self.file_path) - 3} more"
+            return f"Files not found: {head}."
+        return f"File not found: {self.file_path}."
+
+    def get_error_code(self) -> str:
+        return "FILE_NOT_FOUND"
+
+
+class UnsupportedFileType(SDKException):
+    def __init__(
+        self,
+        file_ext: str,
+        file_name: str,
+        message: Optional[str] = None,
+        cause: Optional[Exception] = None,
+    ) -> None:
+        self.file_ext = file_ext
+        self.file_name = file_name
+        super().__init__(
+            message=message or f"Unsupported file type: '.{file_ext}' for file '{file_name}'.",
+            cause=cause,
+        )
+
+    def get_error_code(self) -> str:
+        return "UNSUPPORTED_FILE_TYPE"

fi/utils/executor.py

@@ -0,0 +1,26 @@
+from concurrent.futures import ThreadPoolExecutor
+from threading import BoundedSemaphore
+
+
+class BoundedExecutor:
+    """ThreadPoolExecutor that blocks on ``submit()`` when the queue is full.
+
+    Keeps memory bounded under burst load without silently dropping work.
+    """
+
+    def __init__(self, bound: int, max_workers: int) -> None:
+        self.executor = ThreadPoolExecutor(max_workers=max_workers)
+        self.semaphore = BoundedSemaphore(bound + max_workers)
+
+    def submit(self, fn, *args, **kwargs):
+        self.semaphore.acquire()
+        try:
+            future = self.executor.submit(fn, *args, **kwargs)
+        except Exception:
+            self.semaphore.release()
+            raise
+        future.add_done_callback(lambda _: self.semaphore.release())
+        return future
+
+    def shutdown(self, wait: bool = True) -> None:
+        self.executor.shutdown(wait)

fi/utils/routes.py

@@ -0,0 +1,119 @@
+"""Backend route paths — single source of truth for url suffixes.
+
+Relative paths (no leading slash). Callers prepend the base URL from the
+``FI_BASE_URL`` env var or client init.
+"""
+from enum import Enum
+
+
+class Routes(str, Enum):
+    # -------------------- Health / logging --------------------
+    healthcheck = "healthcheck"
+    log_model = "sdk/api/v1/log/model/"
+
+    # -------------------- Eval run (sync + async) --------------
+    evaluate = "sdk/api/v1/eval/"
+    evaluatev2 = "sdk/api/v1/new-eval/"
+    evaluate_template = "sdk/api/v1/eval/{eval_id}/"
+    get_eval_templates = "sdk/api/v1/get-evals/"
+    get_eval_result = "sdk/api/v1/new-eval/"
+    evaluate_pipeline = "sdk/api/v1/evaluate-pipeline/"
+    configure_evaluations = "sdk/api/v1/configure-evaluations/"
+
+    # -------------------- Eval templates (revamp) --------------
+    eval_template_list = "model-hub/eval-templates/list/"
+    eval_template_list_charts = "model-hub/eval-templates/list-charts/"
+    eval_template_detail = "model-hub/eval-templates/{template_id}/detail/"
+    eval_template_create_v2 = "model-hub/eval-templates/create-v2/"
+    eval_template_update_v2 = "model-hub/eval-templates/{template_id}/update/"
+    eval_template_delete = "model-hub/delete-eval-template/"
+    eval_template_bulk_delete = "model-hub/eval-templates/bulk-delete/"
+    eval_template_duplicate = "model-hub/duplicate-eval-template/"
+    eval_template_usage = "model-hub/eval-templates/{template_id}/usage/"
+    eval_template_feedback_list = "model-hub/eval-templates/{template_id}/feedback-list/"
+
+    # Versions
+    eval_template_version_list = "model-hub/eval-templates/{template_id}/versions/"
+    eval_template_version_create = "model-hub/eval-templates/{template_id}/versions/create/"
+    eval_template_version_set_default = (
+        "model-hub/eval-templates/{template_id}/versions/{version_id}/set-default/"
+    )
+    eval_template_version_restore = (
+        "model-hub/eval-templates/{template_id}/versions/{version_id}/restore/"
+    )
+
+    # Composite evals
+    composite_eval_create = "model-hub/eval-templates/create-composite/"
+    composite_eval_detail = "model-hub/eval-templates/{template_id}/composite/"
+    composite_eval_execute = "model-hub/eval-templates/{template_id}/composite/execute/"
+    composite_eval_execute_adhoc = "model-hub/eval-templates/composite/execute-adhoc/"
+
+    # Ground truth (data + config)
+    ground_truth_list = "model-hub/eval-templates/{template_id}/ground-truth/"
+    ground_truth_upload = "model-hub/eval-templates/{template_id}/ground-truth/upload/"
+    ground_truth_config = "model-hub/eval-templates/{template_id}/ground-truth-config/"
+    ground_truth_mapping = "model-hub/ground-truth/{ground_truth_id}/mapping/"
+    ground_truth_role_mapping = "model-hub/ground-truth/{ground_truth_id}/role-mapping/"
+    ground_truth_data = "model-hub/ground-truth/{ground_truth_id}/data/"
+    ground_truth_status = "model-hub/ground-truth/{ground_truth_id}/status/"
+    ground_truth_search = "model-hub/ground-truth/{ground_truth_id}/search/"
+    ground_truth_embed = "model-hub/ground-truth/{ground_truth_id}/embed/"
+    ground_truth_delete = "model-hub/ground-truth/{ground_truth_id}/"
+
+    # Playground
+    eval_playground = "model-hub/eval-playground/"
+    eval_playground_feedback = "model-hub/eval-playground/feedback/"
+    eval_sdk_code = "model-hub/eval-sdk-code/"
+
+    # -------------------- Dataset --------------------
+    dataset = "model-hub/develops"
+    dataset_names = "model-hub/develops/get-datasets-names/"
+    dataset_empty = "model-hub/develops/create-empty-dataset/"
+    dataset_local = "model-hub/develops/create-dataset-from-local-file/"
+    dataset_huggingface = "model-hub/develops/create-dataset-from-huggingface/"
+    dataset_table = "model-hub/develops/{dataset_id}/get-dataset-table/"
+    dataset_delete = "model-hub/develops/delete_dataset/"
+    dataset_add_rows = "model-hub/develops/{dataset_id}/add_rows/"
+    dataset_add_columns = "model-hub/develops/{dataset_id}/add_columns/"
+    dataset_add_run_prompt_column = "model-hub/develops/add_run_prompt_column/"
+    dataset_add_evaluation = "model-hub/develops/{dataset_id}/add_user_eval/"
+    dataset_optimization_create = "model-hub/optimisation/create/"
+    dataset_eval_stats = "model-hub/dataset/{dataset_id}/eval-stats/"
+
+    # -------------------- Prompt templates --------------------
+    generate_prompt = "model-hub/prompt-templates/generate-prompt/"
+    improve_prompt = "model-hub/prompt-templates/improve-prompt/"
+    run_template = "model-hub/prompt-templates/{template_id}/run_template/"
+    create_template = "model-hub/prompt-templates/create-draft/"
+    delete_template = "model-hub/prompt-templates/{template_id}/"
+    get_template_by_id = "model-hub/prompt-templates/{template_id}/"
+    get_template_id_by_name = "model-hub/prompt-templates/"
+    list_templates = "model-hub/prompt-templates/"
+    get_template_by_name = "model-hub/prompt-templates/get-template-by-name/"
+    add_new_draft = "model-hub/prompt-templates/{template_id}/add-new-draft/"
+    get_template_version_history = "model-hub/prompt-history-executions/"
+    get_model_details = "model-hub/api/models_list/"
+    get_run_status = "model-hub/prompt-templates/{template_id}/get-run-status/"
+    commit_template = "model-hub/prompt-templates/{template_id}/commit/"
+
+    # -------------------- Prompt labels --------------------
+    prompt_labels = "model-hub/prompt-labels/"
+    prompt_label_get_by_name = "model-hub/prompt-labels/get-by-name/"
+    prompt_label_remove = "model-hub/prompt-labels/remove/"
+    prompt_label_assign_by_id = "model-hub/prompt-labels/{template_id}/{label_id}/assign-label-by-id/"
+    prompt_label_set_default = "model-hub/prompt-labels/set-default/"
+    prompt_label_template_labels = "model-hub/prompt-labels/template-labels/"
+
+    # -------------------- Providers / keys --------------------
+    model_hub_api_keys = "model-hub/api-keys/"
+    model_hub_default_provider = "model-hub/default-provider/"
+
+    # -------------------- Knowledge base --------------------
+    knowledge_base = "model-hub/knowledge-base/"
+    knowledge_base_list = "model-hub/knowledge-base/list/"
+    knowledge_base_files = "model-hub/knowledge-base/files/"
+
+    # -------------------- Tracer --------------------
+    bulk_annotation = "tracer/bulk-annotation/"
+    get_annotation_labels = "tracer/get-annotation-labels/"
+    list_projects = "tracer/project/list_projects/"

fi/utils/utils.py

@@ -0,0 +1,17 @@
+import os
+
+from .constants import get_base_url
+from .errors import InvalidAuthError
+
+
+def get_base_url_from_env() -> str:
+    """Backward-compat alias — use ``get_base_url()`` from constants."""
+    return get_base_url()
+
+
+def get_keys_from_env() -> tuple[str, str]:
+    api_key = os.getenv("FI_API_KEY")
+    secret_key = os.getenv("FI_SECRET_KEY")
+    if not api_key or not secret_key:
+        raise InvalidAuthError()
+    return api_key, secret_key