viscribe 0.1.0 → 1.0.5

package/README.md

@@ -1,26 +1,25 @@
 <div align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="./assets/white-v.png">
-    <source media="(prefers-color-scheme: light)" srcset="./assets/black-v.png">
-    <img src="./assets/black-v.png" alt="Viscribe" width="160">
-  </picture>
+  <img src="./assets/viscribe-hero.png" alt="ViscribeAI" width="860">
 
   <h1>ViscribeAI</h1>
 
   <p>Extract <strong>structured data</strong> from <strong>images</strong> using <strong>AI models</strong>.</p>
 
   <p>
+    <a href="https://x.com/itsperini"><img alt="X @itsperini" src="https://img.shields.io/badge/X-@itsperini-000000?logo=x&logoColor=white"></a>
+    <a href="https://discord.gg/GVgJ9ujT"><img alt="Discord" src="https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white"></a>
+    <a href="https://docs.viscribe.ai"><img alt="Docs docs.viscribe.ai" src="https://img.shields.io/badge/-docs.viscribe.ai-2563EB?logo=bookstack&logoColor=white"></a>
     <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-3776AB">
     <img alt="Node.js 20+" src="https://img.shields.io/badge/node.js-20%2B-339933">
     <img alt="License MIT" src="https://img.shields.io/badge/license-MIT-blue">
-    <a href="https://x.com/itsperini"><img alt="X @itsperini" src="https://img.shields.io/badge/X-@itsperini-000000?logo=x&logoColor=white"></a>
-    <img alt="Discord coming soon" src="https://img.shields.io/badge/discord-coming_soon-5865F2?logo=discord&logoColor=white">
-    <a href="https://docs.viscribe.ai"><img alt="Docs docs.viscribe.ai" src="https://img.shields.io/badge/docs-docs.viscribe.ai-2563EB"></a>
   </p>
 </div>
 
 > Define the output schema, pass the image, pick the AI model, and get parsed
-structured output back instead of free-form text.
+> structured output back instead of free-form text.
+
+⭐ If Viscribe helps your project, please leave a
+[star](https://github.com/itsperini/viscribe). ⭐
 
 ## 📦 Installation
 
@@ -54,9 +53,9 @@ result = describe(
     # image_base64="...",
     generate_tags=True,
     model_config={
-        "model": "gpt-4o-mini",
+        "model": "gpt-5-mini",
         "api_key": "sk-...",
-        "temperature": 0,
+        "temperature": 1,
     },
 )
 
@@ -82,9 +81,9 @@ const result = await images.describe({
   imagePath: "examples/venice.png",
   generateTags: true,
   modelConfig: {
-    model: "gpt-4o-mini",
+    model: "gpt-5-mini",
     apiKey: "sk-...",
-    temperature: 0,
+    temperature: 1,
   },
 });
 
@@ -98,6 +97,14 @@ console.log(result);
 
 ## 📚 Image Endpoints
 
+| Method     | Description                                                                                            |
+| ---------- | ------------------------------------------------------------------------------------------------------ |
+| `describe` | Generate an objective image description with optional tags.                                            |
+| `classify` | Classify an image into one or more allowed or free-form categories.                                    |
+| `ask`      | Ask a visual question and get an answer grounded in the image.                                         |
+| `extract`  | Extract structured data from an image using simple fields, JSON Schema, or a Pydantic model in Python. |
+| `compare`  | Compare two images and describe their similarities and differences.                                    |
+
 ### 1. Describe Image
 
 Generate a natural language description of an image, optionally with tags.
@@ -109,9 +116,9 @@ result = describe(
     image_path="examples/venice.png",
     generate_tags=True,
     model_config={
-        "model": "gpt-4o-mini",
+        "model": "gpt-5-mini",
         "api_key": "sk-...",
-        "temperature": 0,
+        "temperature": 1,
     },
 )
 
@@ -128,9 +135,9 @@ const result = await images.describe({
   imagePath: "examples/venice.png",
   generateTags: true,
   modelConfig: {
-    model: "gpt-4o-mini",
+    model: "gpt-5-mini",
     apiKey: "sk-...",
-    temperature: 0,
+    temperature: 1,
   },
 });
 
@@ -151,9 +158,9 @@ result = classify(
     classes=["canal", "city", "landmark", "interior"],
     multi_label=True,
     model_config={
-        "model": "gpt-4o-mini",
+        "model": "gpt-5-mini",
         "api_key": "sk-...",
-        "temperature": 0,
+        "temperature": 1,
     },
 )
 
@@ -171,9 +178,9 @@ const result = await images.classify({
   classes: ["canal", "city", "landmark", "interior"],
   multiLabel: true,
   modelConfig: {
-    model: "gpt-4o-mini",
+    model: "gpt-5-mini",
     apiKey: "sk-...",
-    temperature: 0,
+    temperature: 1,
   },
 });
 
@@ -193,9 +200,9 @@ result = ask(
     image_path="examples/venice.png",
     question="What kind of place is shown in this image?",
     model_config={
-        "model": "gpt-4o-mini",
+        "model": "gpt-5-mini",
         "api_key": "sk-...",
-        "temperature": 0,
+        "temperature": 1,
     },
 )
 
@@ -212,9 +219,9 @@ const result = await images.ask({
   imagePath: "examples/venice.png",
   question: "What kind of place is shown in this image?",
   modelConfig: {
-    model: "gpt-4o-mini",
+    model: "gpt-5-mini",
     apiKey: "sk-...",
-    temperature: 0,
+    temperature: 1,
   },
 });
 
@@ -242,9 +249,9 @@ result = extract(
         {"name": "colors", "type": "array_text", "description": "Dominant colors"},
     ],
     model_config={
-        "model": "gpt-4o-mini",
+        "model": "gpt-5-mini",
         "api_key": "sk-...",
-        "temperature": 0,
+        "temperature": 1,
     },
 )
 
@@ -269,9 +276,9 @@ const result = await images.extract({
     { name: "colors", type: "array_text", description: "Dominant colors" },
   ],
   modelConfig: {
-    model: "gpt-4o-mini",
+    model: "gpt-5-mini",
     apiKey: "sk-...",
-    temperature: 0,
+    temperature: 1,
   },
 });
 
@@ -306,9 +313,9 @@ result = extract(
     image_path="examples/venice.png",
     output_schema=Scene,
     model_config={
-        "model": "gpt-4o-mini",
+        "model": "gpt-5-mini",
         "api_key": "sk-...",
-        "temperature": 0,
+        "temperature": 1,
     },
 )
 
@@ -338,9 +345,9 @@ const result = await images.extract({
     additionalProperties: false,
   },
   modelConfig: {
-    model: "gpt-4o-mini",
+    model: "gpt-5-mini",
     apiKey: "sk-...",
-    temperature: 0,
+    temperature: 1,
   },
 });
 
@@ -362,9 +369,9 @@ result = compare(
     image1_path="examples/venice.png",
     image2_path="examples/venice.png",
     model_config={
-        "model": "gpt-4o-mini",
+        "model": "gpt-5-mini",
         "api_key": "sk-...",
-        "temperature": 0,
+        "temperature": 1,
     },
 )
 
@@ -381,9 +388,9 @@ const result = await images.compare({
   image1Path: "examples/venice.png",
   image2Path: "examples/venice.png",
   modelConfig: {
-    model: "gpt-4o-mini",
+    model: "gpt-5-mini",
     apiKey: "sk-...",
-    temperature: 0,
+    temperature: 1,
   },
 });
 
@@ -406,9 +413,9 @@ async def main() -> None:
         image_path="examples/venice.png",
         generate_tags=True,
         model_config={
-            "model": "gpt-4o-mini",
+            "model": "gpt-5-mini",
             "api_key": "sk-...",
-            "temperature": 0,
+            "temperature": 1,
         },
     )
 
@@ -428,9 +435,9 @@ from viscribe import ViscribeAI
 async def main() -> None:
     client = ViscribeAI(
         model_config={
-            "model": "gpt-4o-mini",
+            "model": "gpt-5-mini",
             "api_key": "sk-...",
-            "temperature": 0,
+            "temperature": 1,
         }
     )
 
@@ -457,9 +464,9 @@ const result = await images.describe({
   imagePath: "examples/venice.png",
   generateTags: true,
   modelConfig: {
-    model: "gpt-4o-mini",
+    model: "gpt-5-mini",
     apiKey: "sk-...",
-    temperature: 0,
+    temperature: 1,
   },
 });
 
@@ -467,9 +474,9 @@ console.log(result.data);
 
 const client = new ViscribeAI({
   modelConfig: {
-    model: "gpt-4o-mini",
+    model: "gpt-5-mini",
     apiKey: "sk-...",
-    temperature: 0,
+    temperature: 1,
   },
 });
 
@@ -503,7 +510,7 @@ Feel free to contribute and join our Discord server to discuss with us improveme
 
 Please see the [contributing guidelines](./CONTRIBUTING.md).
 
-[![My Skills](https://skillicons.dev/icons?i=discord)](https://discord.gg/uJN7TYcp)
+[![My Skills](https://skillicons.dev/icons?i=discord)](https://discord.gg/GVgJ9ujT)
 [![My Skills](https://skillicons.dev/icons?i=linkedin)](https://www.linkedin.com/in/itsperini)
 [![My Skills](https://skillicons.dev/icons?i=twitter)](https://twitter.com/itsperini)
 
@@ -517,6 +524,9 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - [Documentation](https://docs.viscribe.ai)
 - [GitHub](https://github.com/itsperini/viscribe)
 
+⭐ If Viscribe helps your project, please leave a
+[star](https://github.com/itsperini/viscribe). ⭐
+
 ---
 
 Made with ❤️ by [ViscribeAI](https://viscribe.ai)

package/dist/index.cjs

@@ -68,9 +68,7 @@ function buildImageSource(input) {
     input.imagePath !== void 0
   ].filter(Boolean).length;
   if (provided !== 1) {
-    throw new Error(
-      "Provide exactly one of 'imageUrl', 'imageBase64', or 'imagePath'."
-    );
+    throw new Error("Provide exactly one of 'imageUrl', 'imageBase64', or 'imagePath'.");
   }
   if (input.imageUrl !== void 0) {
     validateImageUrl(input.imageUrl);
@@ -90,9 +88,7 @@ function buildImageSource(input) {
     const mimeType = detectImageMimeType(imageBytes);
     return `data:${mimeType};base64,${input.imageBase64}`;
   }
-  throw new Error(
-    "Provide exactly one of 'imageUrl', 'imageBase64', or 'imagePath'."
-  );
+  throw new Error("Provide exactly one of 'imageUrl', 'imageBase64', or 'imagePath'.");
 }
 async function assertImagePathExists(imagePath) {
   const result = await (0, import_promises.stat)(imagePath);
@@ -617,9 +613,7 @@ function normalizeClassification(data, options) {
   }
   if (options.classes) {
     const allowedClasses = new Set(options.classes);
-    classification = classification.filter(
-      (className) => allowedClasses.has(className)
-    );
+    classification = classification.filter((className) => allowedClasses.has(className));
   }
   return { classification };
 }
@@ -738,9 +732,7 @@ function messageContentText(message) {
     ).map((block) => block.text).join("");
     if (text) return text;
   }
-  throw new StructuredOutputParseError(
-    "Response message does not contain text content."
-  );
+  throw new StructuredOutputParseError("Response message does not contain text content.");
 }
 function loadsJsonObject(content) {
   const trimmed = content.trim();
@@ -761,9 +753,7 @@ function loadsJsonObject(content) {
     try {
       const data = JSON.parse(attempt);
       if (!isPlainObject(data)) {
-        throw new StructuredOutputParseError(
-          "Structured output must be a JSON object."
-        );
+        throw new StructuredOutputParseError("Structured output must be a JSON object.");
       }
       return data;
     } catch (error) {

package/dist/index.js

@@ -30,9 +30,7 @@ function buildImageSource(input) {
     input.imagePath !== void 0
   ].filter(Boolean).length;
   if (provided !== 1) {
-    throw new Error(
-      "Provide exactly one of 'imageUrl', 'imageBase64', or 'imagePath'."
-    );
+    throw new Error("Provide exactly one of 'imageUrl', 'imageBase64', or 'imagePath'.");
   }
   if (input.imageUrl !== void 0) {
     validateImageUrl(input.imageUrl);
@@ -52,9 +50,7 @@ function buildImageSource(input) {
     const mimeType = detectImageMimeType(imageBytes);
     return `data:${mimeType};base64,${input.imageBase64}`;
   }
-  throw new Error(
-    "Provide exactly one of 'imageUrl', 'imageBase64', or 'imagePath'."
-  );
+  throw new Error("Provide exactly one of 'imageUrl', 'imageBase64', or 'imagePath'.");
 }
 async function assertImagePathExists(imagePath) {
   const result = await stat(imagePath);
@@ -579,9 +575,7 @@ function normalizeClassification(data, options) {
   }
   if (options.classes) {
     const allowedClasses = new Set(options.classes);
-    classification = classification.filter(
-      (className) => allowedClasses.has(className)
-    );
+    classification = classification.filter((className) => allowedClasses.has(className));
   }
   return { classification };
 }
@@ -700,9 +694,7 @@ function messageContentText(message) {
     ).map((block) => block.text).join("");
     if (text) return text;
   }
-  throw new StructuredOutputParseError(
-    "Response message does not contain text content."
-  );
+  throw new StructuredOutputParseError("Response message does not contain text content.");
 }
 function loadsJsonObject(content) {
   const trimmed = content.trim();
@@ -723,9 +715,7 @@ function loadsJsonObject(content) {
     try {
       const data = JSON.parse(attempt);
       if (!isPlainObject(data)) {
-        throw new StructuredOutputParseError(
-          "Structured output must be a JSON object."
-        );
+        throw new StructuredOutputParseError("Structured output must be a JSON object.");
       }
       return data;
     } catch (error) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "viscribe",
-  "version": "0.1.0",
-  "description": "OpenAI-compatible image understanding SDK for structured extraction, description, classification, VQA, and comparison.",
+  "version": "1.0.5",
+  "description": "Extract structured data from images using AI models.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",