بسم الله الرحمن الرحيم

Ghaymah Serverless Vector Store

Overview

كَنْزُ المَعْلُومَات (Kanz al-Ma'lumat) is a robust, classical vector store designed for efficient similarity search. It's built to be seamlessly deployed on the Ghaymah serverless platform, allowing you to focus on your application logic without managing infrastructure. This project provides a Docker image for easy deployment and integration into your Ghaymah workflows.

This vector store is a foundational component for building intelligent applications that rely on semantic search, recommendation systems, and more. It stores vector embeddings along with associated payloads, enabling fast retrieval of the most similar vectors based on a query vector.

Key Features

Serverless Deployment: Effortlessly deploy and scale on Ghaymah.
Classical Vector Store: Provides core vector store functionality with a focus on reliability and performance.
Docker Image: A pre-built Docker image simplifies deployment and integration. (Available soon, InshAllah)
REST API: Interact with the vector store via a simple and intuitive REST API.
Scalability: Leverage Ghaymah's serverless architecture for automatic scaling.

Getting Started

Prerequisites

A Ghaymah account. (Sign up at https://ghaymah.systems)
Docker installed locally (for testing).
curl or a similar tool for making HTTP requests.

Deployment (on Ghaymah)

Pull the Docker Image: (Image will be available soon, InshAllah). We will provide the Docker Hub image tag link.
```
docker pull <ghaymah_docker_hub_image_tag>
```
Deploy to Ghaymah: Use the Ghaymah CLI or web interface to deploy the Docker image to a Ghaymah function. Configure the function with sufficient memory and resources based on your expected workload.

Local Testing (with Docker)

Run the Docker Image:
```
docker run -p 8000:8000 <ghaymah_docker_hub_image_tag>
```
This will start the vector store on http://localhost:8000.

API Reference

The vector store exposes the following REST API endpoints:

/insert (POST): Inserts vectors and their associated payloads into the store.

Request Body (JSON):

{
  "vectors": [
    [0.1, 0.2, ..., 0.512],  // List of 512-dimensional vectors
    [...],
    ...
  ],
  "payloads": [
    {"key1": "value1"},     // Payload associated with the first vector
    {"key2": "value2"},     // Payload associated with the second vector
    ...
  ]
}

Response: JSON object indicating success or failure.

/search (POST): Searches for the k most similar vectors to a given query vector.
- Request Body (JSON):
```
{
  "vector": [0.1, 0.2, ..., 0.512],  // The query vector (512 dimensions)
  "k": 3                          // The number of results to return
}
```
- Response (JSON): JSON object containing a list of results, each with the vector ID, similarity score, and payload.

Example Usage (Python)

#!/usr/bin/env python3

import random
import json
import requests

HOST = "https://serverless-store-77838979b96f.hosted.ghaymah.systems"  # Replace with your deployed endpoint
N_DIM = 512

def random_vector():
    """512-length float list, small random numbers just for demo."""
    return [random.random() for _ in range(N_DIM)]

# ===== 1) /insert ====
# vectors_to_insert = [random_vector() for _ in range(2)]
# payloads = [{"aaaa": "sssa"}, {"tasd": "asb"}]

# insert_resp = requests.post(
#     f"{HOST}/insert",
#     json={"vectors": vectors_to_insert, "payloads": payloads},
#     headers={"Content-Type": "application/json"}
# )
# print("→ POST /insert")
# print(insert_resp.status_code, insert_resp.text)

# ===== 2) /search ====
query_vec = random_vector()
k = 3

search_resp = requests.post(
    f"{HOST}/search",
    json={"vector": query_vec, "k": k},
    headers={"Content-Type": "application/json"}
)
print("\n→ POST /search")
print(search_resp.status_code, json.dumps(search_resp.json(), indent=2))