commit 40ee5b4a46c873b8a6b2411f3d11f9641d605dac
Author: ghaymah_dev <hr@ghaymah.systems>
Date:   Sun Aug 17 04:53:50 2025 +0000

    Add README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a711a80
--- /dev/null
+++ b/README.md
@@ -0,0 +1,115 @@
+# بسم الله الرحمن الرحيم
+
+# 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](https://ghaymah.systems))
+*   Docker installed locally (for testing).
+*   `curl` or a similar tool for making HTTP requests.
+
+### Deployment (on Ghaymah)
+
+1.  **Pull the Docker Image:** (Image will be available soon, *InshAllah*).  We will provide the Docker Hub image tag link.
+    ```bash
+    docker pull <ghaymah_docker_hub_image_tag>
+    ```
+
+2.  **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)
+
+1.  **Run the Docker Image:**
+    ```bash
+    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):**
+        ```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):**
+        ```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)
+
+```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))
\ No newline at end of file