docs: update README and USAGE for card-renderer, Qdrant optimization endpoints, and search params

README.md

@@ -1,6 +1,6 @@
-# Skinbase Vision Stack (CLIP + BLIP + YOLO + Qdrant) – Dockerized FastAPI
+# Skinbase Vision Stack (CLIP + BLIP + YOLO + Qdrant + Card Renderer) – Dockerized FastAPI
 
-This repository provides **four standalone vision services** (CLIP / BLIP / YOLO / Qdrant)
+This repository provides **five standalone vision services** (CLIP / BLIP / YOLO / Qdrant / Card Renderer)
 and a **Gateway API** that can call them individually or together.
 
 ## Services & Ports
@@ -11,6 +11,7 @@ and a **Gateway API** that can call them individually or together.
 - `yolo`: internal only
 - `qdrant`: vector DB (port `6333` exposed for direct access)
 - `qdrant-svc`: internal Qdrant API wrapper
+- `card-renderer`: internal card rendering service
 
 ## Run
 
@@ -129,14 +130,17 @@ curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/up
 ```bash
 curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/search \
   -H "Content-Type: application/json" \
-  -d '{"url":"https://files.skinbase.org/img/aa/bb/cc/md.webp","limit":5}'
+  -d '{"url":"https://files.skinbase.org/img/aa/bb/cc/md.webp","limit":5,"filter_metadata":{"is_public":true}}'
 ```
 
+Optional search parameters: `hnsw_ef` (int), `exact` (bool), `indexed_only` (bool), `score_threshold` (float), `filter_metadata` (object).
+
 ### Search similar images by file upload
 ```bash
 curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/search/file \
   -F "file=@/path/to/image.webp" \
-  -F "limit=5"
+  -F "limit=5" \
+  -F 'filter_metadata_json={"is_public":true}'
 ```
 
 ### List collections
@@ -149,6 +153,38 @@ curl -H "X-API-Key: <your-api-key>" https://vision.klevze.net/vectors/collection
 curl -H "X-API-Key: <your-api-key>" https://vision.klevze.net/vectors/collections/images
 ```
 
+### Full diagnostic inspect
+```bash
+curl -H "X-API-Key: <your-api-key>" https://vision.klevze.net/vectors/inspect
+```
+
+Returns HNSW config, optimizer config, quantization, segment count, payload index coverage, and RAM estimate for every collection.
+
+### Payload index management
+```bash
+# List indexes
+curl -H "X-API-Key: <your-api-key>" https://vision.klevze.net/vectors/collections/images/indexes
+
+# Create a single index
+curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/collections/images/indexes \
+  -H "Content-Type: application/json" \
+  -d '{"field":"is_public","type":"bool"}'
+
+# Ensure multiple indexes (idempotent)
+curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/collections/images/ensure-indexes \
+  -H "Content-Type: application/json" \
+  -d '{"fields":[{"field":"is_public","type":"bool"},{"field":"category_id","type":"integer"}]}'
+```
+
+Supported index types: `keyword`, `integer`, `float`, `bool`, `geo`, `datetime`, `text`, `uuid`.
+
+### Collection configuration (HNSW / optimizer / quantization)
+```bash
+curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/collections/images/configure \
+  -H "Content-Type: application/json" \
+  -d '{"hnsw_m":16,"hnsw_ef_construct":200,"indexing_threshold":20000,"quantization_type":"int8"}'
+```
+
 ### Delete points
 ```bash
 curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/delete \
@@ -158,6 +194,38 @@ curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/vectors/de
 
 If you let the wrapper generate a UUID, use the returned `id` value for later `get`, `search`, or `delete` operations.
 
+## Card Renderer
+
+### List available templates
+```bash
+curl -H "X-API-Key: <your-api-key>" https://vision.klevze.net/cards/templates
+```
+
+### Render a card from a URL
+```bash
+curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/cards/render \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://files.skinbase.org/img/aa/bb/cc/md.webp","title":"Artwork Title","username":"@artist","template":"nova-artwork-v1"}'
+```
+
+Returns binary image bytes (WebP by default).
+
+### Render a card from a file upload
+```bash
+curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/cards/render/file \
+  -F "file=@/path/to/image.webp" \
+  -F "title=Artwork Title" \
+  -F "username=@artist" \
+  -F "template=nova-artwork-v1"
+```
+
+### Get card layout metadata (no image rendered)
+```bash
+curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/cards/render/meta \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://files.skinbase.org/img/aa/bb/cc/md.webp","title":"Artwork Title"}'
+```
+
 ## Notes
 
 - This is a **starter scaffold**. Models are loaded at service startup.