Merge pull request #26 from moorcheh-ai/feat/head-foot-prompt-ai

Feat: add header and footer prompt parameter

Author: Neelpatel1604

moorcheh_sdk/_legacy_client.py

@@ -1,5 +1,20 @@
 import warnings
-from typing import TYPE_CHECKING, Any, Protocol
+from typing import TYPE_CHECKING, Protocol
+
+from .types import (
+    AnswerResponse,
+    ChatHistoryItem,
+    Document,
+    DocumentDeleteResponse,
+    DocumentGetResponse,
+    DocumentUploadResponse,
+    NamespaceCreateResponse,
+    NamespaceListResponse,
+    SearchResponse,
+    Vector,
+    VectorDeleteResponse,
+    VectorUploadResponse,
+)
 
 if TYPE_CHECKING:
     from .resources import Answer, Documents, Namespaces, Search, Vectors
@@ -24,7 +39,7 @@ def create_namespace(
         namespace_name: str,
         type: str,
         vector_dimension: int | None = None,
-    ) -> dict[str, Any]:
+    ) -> NamespaceCreateResponse:
         """
         [DEPRECATED] Creates a new namespace.
 
@@ -73,7 +88,7 @@ def delete_namespace(self: "ClientProtocol", namespace_name: str) -> None:
         )
         self.namespaces.delete(namespace_name=namespace_name)
 
-    def list_namespaces(self: "ClientProtocol") -> dict[str, Any]:
+    def list_namespaces(self: "ClientProtocol") -> NamespaceListResponse:
         """
         [DEPRECATED] Lists all available namespaces.
 
@@ -104,8 +119,8 @@ def list_namespaces(self: "ClientProtocol") -> dict[str, Any]:
         return self.namespaces.list()
 
     def upload_documents(
-        self: "ClientProtocol", namespace_name: str, documents: list[dict[str, Any]]
-    ) -> dict[str, Any]:
+        self: "ClientProtocol", namespace_name: str, documents: list[Document]
+    ) -> DocumentUploadResponse:
         """
         [DEPRECATED] Uploads text documents to a text-based namespace.
 
@@ -138,7 +153,7 @@ def upload_documents(
 
     def get_documents(
         self: "ClientProtocol", namespace_name: str, ids: list[str | int]
-    ) -> dict[str, Any]:
+    ) -> DocumentGetResponse:
         """
         [DEPRECATED] Retrieves documents by their IDs from a text-based namespace.
 
@@ -171,8 +186,8 @@ def get_documents(
         return self.documents.get(namespace_name=namespace_name, ids=ids)
 
     def upload_vectors(
-        self: "ClientProtocol", namespace_name: str, vectors: list[dict[str, Any]]
-    ) -> dict[str, Any]:
+        self: "ClientProtocol", namespace_name: str, vectors: list[Vector]
+    ) -> VectorUploadResponse:
         """
         [DEPRECATED] Uploads pre-computed vectors to a vector-based namespace.
 
@@ -209,9 +224,9 @@ def search(
         namespaces: list[str],
         query: str | list[float],
         top_k: int = 10,
-        threshold: float | None = 0.7,
+        threshold: float | None = 0.25,
         kiosk_mode: bool = False,
-    ) -> dict[str, Any]:
+    ) -> SearchResponse:
         """
         [DEPRECATED] Performs a semantic search across namespaces.
 
@@ -221,7 +236,7 @@ def search(
             namespaces: A list of namespace names to search within.
             query: The search query (text string or vector list).
             top_k: The maximum number of results to return. Defaults to 10.
-            threshold: Minimum similarity score (0-1). Defaults to 0.7.
+            threshold: Minimum similarity score (0-1). Defaults to 0.25.
             kiosk_mode: Enable strict filtering. Defaults to False.
 
         Returns:
@@ -260,9 +275,11 @@ def get_generative_answer(
         query: str,
         top_k: int = 5,
         ai_model: str = "anthropic.claude-sonnet-4-20250514-v1:0",
-        chat_history: list[dict[str, Any]] | None = None,
+        chat_history: list[ChatHistoryItem] | None = None,
         temperature: float = 0.7,
-    ) -> dict[str, Any]:
+        header_prompt: str | None = None,
+        footer_prompt: str | None = None,
+    ) -> AnswerResponse:
         """
         [DEPRECATED] Generates an AI answer based on a search query within a namespace.
 
@@ -278,6 +295,10 @@ def get_generative_answer(
                 Each item should be a dictionary. Defaults to None.
             temperature: The sampling temperature for the LLM (0.0 to 1.0).
                 Higher values introduce more randomness. Defaults to 0.7.
+            header_prompt: Optional header prompt to be used in the LLM.
+                Defaults to None.
+            footer_prompt: Optional footer prompt to be used in the LLM.
+                Defaults to None.
 
         Returns:
             A dictionary containing the generated answer and metadata.
@@ -303,11 +324,13 @@ def get_generative_answer(
             ai_model=ai_model,
             chat_history=chat_history,
             temperature=temperature,
+            header_prompt=header_prompt,
+            footer_prompt=footer_prompt,
         )
 
     def delete_documents(
         self: "ClientProtocol", namespace_name: str, ids: list[str | int]
-    ) -> dict[str, Any]:
+    ) -> DocumentDeleteResponse:
         """
         [DEPRECATED] Deletes documents by their IDs from a text-based namespace.
 
@@ -337,7 +360,7 @@ def delete_documents(
 
     def delete_vectors(
         self: "ClientProtocol", namespace_name: str, ids: list[str | int]
-    ) -> dict[str, Any]:
+    ) -> VectorDeleteResponse:
         """
         [DEPRECATED] Deletes vectors by their IDs from a vector-based namespace.
 

moorcheh_sdk/resources/answer.py

@@ -1,7 +1,7 @@
-from typing import Any
+from typing import Any, cast
 
 from ..exceptions import APIError, InvalidInputError
-from ..types import JSON
+from ..types import AnswerResponse, ChatHistoryItem
 from ..utils.logging import setup_logging
 from .base import BaseResource
 
@@ -15,9 +15,11 @@ def generate(
         query: str,
         top_k: int = 5,
         ai_model: str = "anthropic.claude-sonnet-4-20250514-v1:0",
-        chat_history: list[JSON] | None = None,
+        chat_history: list[ChatHistoryItem] | None = None,
         temperature: float = 0.7,
-    ) -> JSON:
+        header_prompt: str | None = None,
+        footer_prompt: str | None = None,
+    ) -> AnswerResponse:
         """
         Generates an AI answer based on a search query within a namespace.
 
@@ -34,6 +36,10 @@ def generate(
                 Each item should be a dictionary. Defaults to None.
             temperature: The sampling temperature for the LLM (0.0 to 1.0).
                 Higher values introduce more randomness. Defaults to 0.7.
+            header_prompt: Optional header prompt to be used in the LLM.
+                Defaults to None.
+            footer_prompt: Optional footer prompt to be used in the LLM.
+                Defaults to None.
 
         Returns:
             A dictionary containing the generated answer and metadata.
@@ -80,6 +86,8 @@ def generate(
             "aiModel": ai_model,
             "chatHistory": chat_history if chat_history is not None else [],
             "temperature": temperature,
+            "headerPrompt": header_prompt if header_prompt is not None else "",
+            "footerPrompt": footer_prompt if footer_prompt is not None else "",
         }
         logger.debug(f"Generative answer payload: {payload}")
 
@@ -97,4 +105,4 @@ def generate(
             "Successfully received generative answer. Model used:"
             f" {response_data.get('model')}"
         )
-        return response_data
+        return cast(AnswerResponse, response_data)

moorcheh_sdk/resources/documents.py

@@ -1,5 +1,12 @@
+from typing import cast
+
 from ..exceptions import APIError, InvalidInputError
-from ..types import JSON
+from ..types import (
+    Document,
+    DocumentDeleteResponse,
+    DocumentGetResponse,
+    DocumentUploadResponse,
+)
 from ..utils.constants import INVALID_ID_CHARS
 from ..utils.logging import setup_logging
 from .base import BaseResource
@@ -8,7 +15,9 @@
 
 
 class Documents(BaseResource):
-    def upload(self, namespace_name: str, documents: list[JSON]) -> JSON:
+    def upload(
+        self, namespace_name: str, documents: list[Document]
+    ) -> DocumentUploadResponse:
         """
         Uploads text documents to a text-based namespace.
 
@@ -94,9 +103,9 @@ def upload(self, namespace_name: str, documents: list[JSON]) -> JSON:
             f"Successfully queued {submitted_count} documents for upload to"
             f" '{namespace_name}'. Status: {response_data.get('status')}"
         )
-        return response_data
+        return cast(DocumentUploadResponse, response_data)
 
-    def get(self, namespace_name: str, ids: list[str | int]) -> JSON:
+    def get(self, namespace_name: str, ids: list[str | int]) -> DocumentGetResponse:
         """
         Retrieves documents by their IDs from a text-based namespace.
 
@@ -163,9 +172,11 @@ def get(self, namespace_name: str, ids: list[str | int]) -> JSON:
             f"Successfully retrieved {doc_count} document(s) from namespace"
             f" '{namespace_name}'."
         )
-        return response_data
+        return cast(DocumentGetResponse, response_data)
 
-    def delete(self, namespace_name: str, ids: list[str | int]) -> JSON:
+    def delete(
+        self, namespace_name: str, ids: list[str | int]
+    ) -> DocumentDeleteResponse:
         """
         Deletes documents by their IDs from a text-based namespace.
 
@@ -235,4 +246,4 @@ def delete(self, namespace_name: str, ids: list[str | int]) -> JSON:
             logger.warning(
                 f"Delete documents encountered errors: {response_data.get('errors')}"
             )
-        return response_data
+        return cast(DocumentDeleteResponse, response_data)

moorcheh_sdk/resources/namespaces.py

@@ -1,7 +1,7 @@
-from typing import Any
+from typing import Any, cast
 
 from ..exceptions import APIError, InvalidInputError
-from ..types import JSON
+from ..types import NamespaceCreateResponse, NamespaceListResponse
 from ..utils.logging import setup_logging
 from .base import BaseResource
 
@@ -11,7 +11,7 @@
 class Namespaces(BaseResource):
     def create(
         self, namespace_name: str, type: str, vector_dimension: int | None = None
-    ) -> JSON:
+    ) -> NamespaceCreateResponse:
         """
         Creates a new namespace.
 
@@ -77,7 +77,7 @@ def create(
             f"Successfully created namespace '{namespace_name}'. Response:"
             f" {response_data}"
         )
-        return response_data
+        return cast(NamespaceCreateResponse, response_data)
 
     def delete(self, namespace_name: str) -> None:
         """
@@ -103,7 +103,7 @@ def delete(self, namespace_name: str) -> None:
         # Log success after the request confirms it (no exception raised)
         logger.info(f"Namespace '{namespace_name}' deleted successfully.")
 
-    def list(self) -> JSON:
+    def list(self) -> NamespaceListResponse:
         """
         Lists all available namespaces.
 
@@ -150,4 +150,4 @@ def list(self) -> JSON:
         count = len(response_data.get("namespaces", []))
         logger.info(f"Successfully listed {count} namespace(s).")
         logger.debug(f"List namespaces response data: {response_data}")
-        return response_data
+        return cast(NamespaceListResponse, response_data)

moorcheh_sdk/resources/search.py

@@ -1,7 +1,7 @@
-from typing import Any
+from typing import Any, cast
 
 from ..exceptions import APIError, InvalidInputError
-from ..types import JSON
+from ..types import SearchResponse
 from ..utils.logging import setup_logging
 from .base import BaseResource
 
@@ -14,17 +14,17 @@ def query(
         namespaces: list[str],
         query: str | list[float],
         top_k: int = 10,
-        threshold: float | None = 0.7,
+        threshold: float | None = 0.25,
         kiosk_mode: bool = False,
-    ) -> JSON:
+    ) -> SearchResponse:
         """
         Performs semantic search across namespaces.
 
         Args:
             namespaces: A list of namespace names to search within.
             query: The search query (text string or vector list).
             top_k: The maximum number of results to return. Defaults to 10.
-            threshold: Minimum similarity score (0-1). Defaults to 0.7.
+            threshold: Minimum similarity score (0-1). Defaults to 0.25.
             kiosk_mode: Enable strict filtering. Defaults to False.
 
         Returns:
@@ -77,16 +77,14 @@ def query(
 
         payload: dict[str, Any] = {
             "namespaces": namespaces,
-            "query": query,  # Keep original query type
+            "query": query,
             "top_k": top_k,
             "kiosk_mode": kiosk_mode,
         }
-        if threshold is not None:
+        if kiosk_mode and threshold is not None:
             payload["threshold"] = threshold
 
-        logger.debug(
-            f"Search payload: {payload}"
-        )  # Be careful logging query if it could be sensitive/large
+        logger.debug(f"Search payload: {payload}")
 
         response_data = self._client._request(
             method="POST", endpoint="/search", json_data=payload, expected_status=200
@@ -102,7 +100,5 @@ def query(
             f"Search completed successfully. Found {result_count} result(s). Execution"
             f" time: {exec_time}s."
         )
-        logger.debug(
-            f"Search results: {response_data}"
-        )  # Log full results at debug level
-        return response_data
+        logger.debug(f"Search results: {response_data}")
+        return cast(SearchResponse, response_data)

moorcheh_sdk/resources/vectors.py

@@ -1,13 +1,17 @@
+from typing import cast
+
 from ..exceptions import APIError, InvalidInputError
-from ..types import JSON
+from ..types import Vector, VectorDeleteResponse, VectorUploadResponse
 from ..utils.logging import setup_logging
 from .base import BaseResource
 
 logger = setup_logging(__name__)
 
 
 class Vectors(BaseResource):
-    def upload(self, namespace_name: str, vectors: list[JSON]) -> JSON:
+    def upload(
+        self, namespace_name: str, vectors: list[Vector]
+    ) -> VectorUploadResponse:
         """
         Uploads pre-computed vectors to a vector-based namespace.
 
@@ -100,9 +104,9 @@ def upload(self, namespace_name: str, vectors: list[JSON]) -> JSON:
             logger.warning(
                 f"Upload vectors encountered errors: {response_data.get('errors')}"
             )
-        return response_data
+        return cast(VectorUploadResponse, response_data)
 
-    def delete(self, namespace_name: str, ids: list[str | int]) -> JSON:
+    def delete(self, namespace_name: str, ids: list[str | int]) -> VectorDeleteResponse:
         """
         Deletes vectors by their IDs from a vector-based namespace.
 
@@ -173,4 +177,4 @@ def delete(self, namespace_name: str, ids: list[str | int]) -> JSON:
             logger.warning(
                 f"Delete vectors encountered errors: {response_data.get('errors')}"
             )
-        return response_data
+        return cast(VectorDeleteResponse, response_data)