Update README.md

README.md

@@ -123,79 +123,127 @@ Response:
 ```json
 {
   "status": "healthy",
-  "models_loaded": ["jobbertv2", "jina"],
-  "voyage_available": false
+  "models_loaded": ["jobbertv2", "jobbertv3", "jina"],
+  "voyage_available": false,
+  "api_key_required": false
 }
 ```
 
-### Generate Embeddings
+### Generate Embeddings (Elasticsearch Compatible)
 
-#### JobBERT v2 (Job Titles)
+The main `/embed` endpoint uses Elasticsearch inference API format with model selection via query parameter.
 
+#### Single Text (JobBERT v3 - default)
+
+Without API key:
 ```bash
-curl -X POST http://localhost:7860/embed \
+curl -X POST "http://localhost:7860/embed" \
   -H "Content-Type: application/json" \
   -d '{
-    "texts": ["Software Engineer", "Data Scientist", "Product Manager"],
-    "model": "jobbertv2"
+    "input": "Software Engineer"
   }'
 ```
 
-#### JobBERT v3 (Latest, Recommended)
-
+With API key:
 ```bash
-curl -X POST http://localhost:7860/embed \
+curl -X POST "http://localhost:7860/embed" \
   -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_API_KEY" \
   -d '{
-    "texts": ["Software Engineer", "Data Scientist", "Product Manager"],
-    "model": "jobbertv3"
+    "input": "Software Engineer"
   }'
 ```
 
-#### Jina AI (with task specification)
+Response:
+```json
+{
+  "embedding": [0.123, -0.456, 0.789, ...]
+}
+```
+
+#### Single Text with Model Selection
+
+```bash
+# JobBERT v2
+curl -X POST "http://localhost:7860/embed?model=jobbertv2" \
+  -H "Content-Type: application/json" \
+  -d '{"input": "Data Scientist"}'
+
+# JobBERT v3 (recommended)
+curl -X POST "http://localhost:7860/embed?model=jobbertv3" \
+  -H "Content-Type: application/json" \
+  -d '{"input": "Product Manager"}'
+
+# Jina AI
+curl -X POST "http://localhost:7860/embed?model=jina" \
+  -H "Content-Type: application/json" \
+  -d '{"input": "Machine Learning Engineer"}'
+```
+
+#### Multiple Texts (Batch)
 
 ```bash
-curl -X POST http://localhost:7860/embed \
+curl -X POST "http://localhost:7860/embed?model=jobbertv3" \
   -H "Content-Type: application/json" \
   -d '{
-    "texts": ["What is machine learning?", "How does AI work?"],
-    "model": "jina",
-    "task": "retrieval.query"
+    "input": ["Software Engineer", "Data Scientist", "Product Manager"]
   }'
 ```
 
-**Jina AI Tasks:**
+Response:
+```json
+{
+  "embeddings": [
+    [0.123, -0.456, ...],
+    [0.234, -0.567, ...],
+    [0.345, -0.678, ...]
+  ]
+}
+```
+
+#### Jina AI with Task Type
+
+```bash
+curl -X POST "http://localhost:7860/embed?model=jina&task=retrieval.query" \
+  -H "Content-Type: application/json" \
+  -d '{"input": "What is machine learning?"}'
+```
+
+**Jina AI Tasks (query parameter):**
 - `retrieval.query`: For search queries
 - `retrieval.passage`: For documents
 - `text-matching`: For similarity (default)
-- `classification`: For classification
-- `separation`: For clustering
 
 #### Voyage AI (requires API key)
 
 ```bash
-curl -X POST http://localhost:7860/embed \
+curl -X POST "http://localhost:7860/embed?model=voyage&input_type=document" \
   -H "Content-Type: application/json" \
-  -d '{
-    "texts": ["This is a document to embed"],
-    "model": "voyage",
-    "input_type": "document"
-  }'
+  -d '{"input": "This is a document to embed"}'
 ```
 
-**Voyage AI Input Types:**
+**Voyage AI Input Types (query parameter):**
 - `document`: For documents/passages
 - `query`: For search queries
 
-### Response Format
+### Batch Endpoint (Original Format)
+
+For compatibility, the original batch endpoint is still available at `/embed/batch`:
+
+```bash
+curl -X POST http://localhost:7860/embed/batch \
+  -H "Content-Type: application/json" \
+  -d '{
+    "texts": ["Software Engineer", "Data Scientist"],
+    "model": "jobbertv3"
+  }'
+```
 
+Response includes metadata:
 ```json
 {
-  "embeddings": [
-    [0.123, -0.456, 0.789, ...],
-    [0.234, -0.567, 0.890, ...]
-  ],
-  "model": "jobbertv2",
+  "embeddings": [[0.123, ...], [0.234, ...]],
+  "model": "jobbertv3",
   "dimension": 768,
   "num_texts": 2
 }
@@ -207,48 +255,164 @@ curl -X POST http://localhost:7860/embed \
 curl http://localhost:7860/models
 ```
 
-## Python Client Example
+## Python Client Examples
+
+### Elasticsearch-Compatible Format (Recommended)
 
 ```python
 import requests
 
-url = "http://localhost:7860/embed"
+BASE_URL = "http://localhost:7860"
+API_KEY = "your-api-key-here"  # Optional, only if API key is required
 
-# JobBERT v3 (recommended)
-response = requests.post(url, json={
-    "texts": ["Software Engineer", "Data Scientist"],
-    "model": "jobbertv3"
-})
-result = response.json()
-embeddings = result["embeddings"]
-print(f"Got {len(embeddings)} embeddings of dimension {result['dimension']}")
+# Headers (include API key if required)
+headers = {}
+if API_KEY:
+    headers["Authorization"] = f"Bearer {API_KEY}"
 
-# JobBERT v2
-response = requests.post(url, json={
-    "texts": ["Product Manager"],
-    "model": "jobbertv2"
-})
+# Single embedding (JobBERT v3 - default)
+response = requests.post(
+    f"{BASE_URL}/embed",
+    headers=headers,
+    json={"input": "Software Engineer"}
+)
+result = response.json()
+embedding = result["embedding"]  # Single vector
+print(f"Embedding dimension: {len(embedding)}")
+
+# Single embedding with model selection
+response = requests.post(
+    f"{BASE_URL}/embed?model=jina",
+    headers=headers,
+    json={"input": "Data Scientist"}
+)
+embedding = response.json()["embedding"]
+
+# Batch embeddings
+response = requests.post(
+    f"{BASE_URL}/embed?model=jobbertv3",
+    headers=headers,
+    json={"input": ["Software Engineer", "Data Scientist", "Product Manager"]}
+)
+result = response.json()
+embeddings = result["embeddings"]  # List of vectors
+print(f"Generated {len(embeddings)} embeddings")
 
 # Jina AI with task
-response = requests.post(url, json={
-    "texts": ["What is Python?"],
-    "model": "jina",
-    "task": "retrieval.query"
-})
+response = requests.post(
+    f"{BASE_URL}/embed?model=jina&task=retrieval.query",
+    headers=headers,
+    json={"input": "What is Python?"}
+)
+
+# Voyage AI with input type
+response = requests.post(
+    f"{BASE_URL}/embed?model=voyage&input_type=document",
+    headers=headers,
+    json={"input": "Document text here"}
+)
+```
+
+### Python Client Class with API Key Support
+
+```python
+import requests
+from typing import List, Union, Optional
+
+class EmbeddingClient:
+    def __init__(self, base_url: str, api_key: Optional[str] = None, model: str = "jobbertv3"):
+        self.base_url = base_url
+        self.api_key = api_key
+        self.model = model
+        self.headers = {}
+        if api_key:
+            self.headers["Authorization"] = f"Bearer {api_key}"
+    
+    def embed(self, text: Union[str, List[str]]) -> Union[List[float], List[List[float]]]:
+        """Get embeddings for single text or batch"""
+        response = requests.post(
+            f"{self.base_url}/embed?model={self.model}",
+            headers=self.headers,
+            json={"input": text}
+        )
+        response.raise_for_status()
+        result = response.json()
+        
+        if isinstance(text, str):
+            return result["embedding"]
+        else:
+            return result["embeddings"]
+
+# Usage
+client = EmbeddingClient(
+    base_url="https://YOUR-SPACE.hf.space",
+    api_key="your-api-key-here",  # Optional
+    model="jobbertv3"
+)
+
+# Single embedding
+embedding = client.embed("Software Engineer")
+print(f"Dimension: {len(embedding)}")
+
+# Batch embeddings
+embeddings = client.embed(["Software Engineer", "Data Scientist"])
+print(f"Generated {len(embeddings)} embeddings")
+```
+
+### Batch Format (Original)
+
+```python
+import requests
+
+url = "http://localhost:7860/embed/batch"
 
-# Voyage AI
 response = requests.post(url, json={
-    "texts": ["Document text here"],
-    "model": "voyage",
-    "input_type": "document"
+    "texts": ["Software Engineer", "Data Scientist"],
+    "model": "jobbertv3"
 })
+result = response.json()
+embeddings = result["embeddings"]
+print(f"Model: {result['model']}, Dimension: {result['dimension']}")
 ```
 
 ## Environment Variables
 
 - `PORT`: Server port (default: 7860)
+- `API_KEY`: Your API key for authentication (optional, but recommended for production)
+- `REQUIRE_API_KEY`: Set to `true` to enable API key authentication (default: `false`)
 - `VOYAGE_API_KEY`: Voyage AI API key (optional, required for Voyage embeddings)
 
+### Setting Up API Key Authentication
+
+#### Local Development
+
+```bash
+# Set environment variables
+export API_KEY="your-secret-key-here"
+export REQUIRE_API_KEY="true"
+
+# Run the API
+python api.py
+```
+
+#### Hugging Face Spaces
+
+1. Go to your Space settings
+2. Click on "Variables and secrets"
+3. Add secrets:
+   - Name: `API_KEY`, Value: `your-secret-key-here`
+   - Name: `REQUIRE_API_KEY`, Value: `true`
+4. Restart your Space
+
+#### Docker
+
+```bash
+docker run -p 7860:7860 \
+  -e API_KEY="your-secret-key-here" \
+  -e REQUIRE_API_KEY="true" \
+  embedding-api
+```
+
 ## Interactive Documentation
 
 Once the API is running, visit: