viscribe 1.0.5 → 1.1.0

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
-  <img src="./assets/viscribe-hero.png" alt="ViscribeAI" width="860">
+  <img src="../assets/viscribe-hero.png" alt="ViscribeAI" width="860">
 
-  <h1>ViscribeAI</h1>
+  <h1>ViscribeAI TypeScript</h1>
 
   <p>Extract <strong>structured data</strong> from <strong>images</strong> using <strong>AI models</strong>.</p>
 
@@ -9,7 +9,6 @@
     <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">
   </p>
@@ -18,263 +17,35 @@
 > Define the output schema, pass the image, pick the AI model, and get parsed
 > structured output back instead of free-form text.
 
-⭐ If Viscribe helps your project, please leave a
-[star](https://github.com/itsperini/viscribe). ⭐
-
 ## 📦 Installation
 
-Python:
-
-```bash
-pip install viscribe
-```
-
-TypeScript:
-
 ```bash
 npm install viscribe
 ```
 
 ## 🚀 Features
 
-- 🖼️ AI-powered image description, extraction, classification, VQA (Visual Question Answering), and comparison
-- 🔄 Both sync and async clients
-- 📊 Structured output with Pydantic schemas
-- 🔍 Detailed logging
-- ⚡ Automatic retries
+- 🖼️ One schema-driven `images.extract` helper for image workflows
+- 📊 JSON Schema objects and simple field definitions
+- 📁 Local image paths, base64 images, and remote image URLs
+- ⚙️ Reusable `new ViscribeAI().images.extract` client namespace
+- 🧩 OpenAI-compatible model configuration
+- 🪄 Typed result wrappers for app and agent code
 
 ## 🎯 Quick Start
 
-```python
-from viscribe.images import describe
-
-result = describe(
-    image_path="examples/venice.png",
-    # image_base64="...",
-    generate_tags=True,
-    model_config={
-        "model": "gpt-5-mini",
-        "api_key": "sk-...",
-        "temperature": 1,
-    },
-)
-
-print(result)
-
-# ImageResult(
-#     data={
-#         "image_description": "A scenic view of Venice...",
-#         "tags": ["Venice", "canal", "gondolas"],
-#     },
-#     raw=<OpenAI response>,
-#     usage_metadata={"input_tokens": 123, "output_tokens": 45, ...},
-# )
-```
-
-<details>
-<summary>TypeScript</summary>
-
-```ts
-import { images } from "viscribe";
-
-const result = await images.describe({
-  imagePath: "examples/venice.png",
-  generateTags: true,
-  modelConfig: {
-    model: "gpt-5-mini",
-    apiKey: "sk-...",
-    temperature: 1,
-  },
-});
-
-console.log(result);
-```
-
-</details>
-
-> **Note:**
-> Viscribe works with OpenAI-compatible endpoints (more support coming soon). It is recommended to load your API key from an environment variable instead of hardcoding it in your code.
-
-## 📚 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.
-
-```python
-from viscribe.images import describe
-
-result = describe(
-    image_path="examples/venice.png",
-    generate_tags=True,
-    model_config={
-        "model": "gpt-5-mini",
-        "api_key": "sk-...",
-        "temperature": 1,
-    },
-)
-
-print(result.data)
-```
-
-<details>
-<summary>TypeScript</summary>
-
-```ts
-import { images } from "viscribe";
-
-const result = await images.describe({
-  imagePath: "examples/venice.png",
-  generateTags: true,
-  modelConfig: {
-    model: "gpt-5-mini",
-    apiKey: "sk-...",
-    temperature: 1,
-  },
-});
-
-console.log(result.data);
-```
-
-</details>
-
-### 2. Classify Image
-
-Classify an image into one or more categories.
-
-```python
-from viscribe.images import classify
-
-result = classify(
-    image_path="examples/venice.png",
-    classes=["canal", "city", "landmark", "interior"],
-    multi_label=True,
-    model_config={
-        "model": "gpt-5-mini",
-        "api_key": "sk-...",
-        "temperature": 1,
-    },
-)
-
-print(result.data)
-```
-
-<details>
-<summary>TypeScript</summary>
-
-```ts
-import { images } from "viscribe";
-
-const result = await images.classify({
-  imagePath: "examples/venice.png",
-  classes: ["canal", "city", "landmark", "interior"],
-  multiLabel: true,
-  modelConfig: {
-    model: "gpt-5-mini",
-    apiKey: "sk-...",
-    temperature: 1,
-  },
-});
-
-console.log(result.data);
-```
-
-</details>
-
-### 3. Visual Question Answering (VQA)
-
-Ask a question about the content of an image and get an answer.
-
-```python
-from viscribe.images import ask
-
-result = ask(
-    image_path="examples/venice.png",
-    question="What kind of place is shown in this image?",
-    model_config={
-        "model": "gpt-5-mini",
-        "api_key": "sk-...",
-        "temperature": 1,
-    },
-)
-
-print(result.data)
-```
-
-<details>
-<summary>TypeScript</summary>
-
-```ts
-import { images } from "viscribe";
-
-const result = await images.ask({
-  imagePath: "examples/venice.png",
-  question: "What kind of place is shown in this image?",
-  modelConfig: {
-    model: "gpt-5-mini",
-    apiKey: "sk-...",
-    temperature: 1,
-  },
-});
-
-console.log(result.data);
-```
-
-</details>
-
-### 4. Extract Structured Data from Image
-
-Extract structured data from an image using either a simple or more complex output schema.
-
-#### Simple Schema
-
-Use a simple schema for straightforward data extraction.
-
-```python
-from viscribe.images import extract
-
-result = extract(
-    image_path="examples/venice.png",
-    output_schema=[
-        {"name": "location", "type": "text", "description": "Likely place shown"},
-        {"name": "visible_elements", "type": "array_text", "description": "Objects and structures"},
-        {"name": "colors", "type": "array_text", "description": "Dominant colors"},
-    ],
-    model_config={
-        "model": "gpt-5-mini",
-        "api_key": "sk-...",
-        "temperature": 1,
-    },
-)
-
-print(result.data)
-```
-
-<details>
-<summary>TypeScript</summary>
-
 ```ts
 import { images } from "viscribe";
 
 const result = await images.extract({
-  imagePath: "examples/venice.png",
+  imagePath: "examples/receipt.png",
   outputSchema: [
-    { name: "location", type: "text", description: "Likely place shown" },
-    {
-      name: "visible_elements",
-      type: "array_text",
-      description: "Objects and structures",
-    },
-    { name: "colors", type: "array_text", description: "Dominant colors" },
+    { name: "merchant_name", type: "text", description: "Store or business name" },
+    { name: "total_amount", type: "number", description: "Final total on the receipt" },
+    { name: "date", type: "text", description: "Receipt date if visible" },
+    { name: "line_items", type: "array_text", description: "Visible purchased items" },
   ],
+  instruction: "Extract the receipt fields visible in the image.",
   modelConfig: {
     model: "gpt-5-mini",
     apiKey: "sk-...",
@@ -285,248 +56,46 @@ const result = await images.extract({
 console.log(result.data);
 ```
 
-</details>
-
-**Field Types:**
-
-- `text`: Single text value
-- `number`: Single numeric value
-- `array_text`: Array of text values
-- `array_number`: Array of numeric values
-
-#### More Complex Schema
-
-Use a Pydantic model as the `output_schema` when you need complex or nested structures.
-
-```python
-from pydantic import BaseModel
-from viscribe.images import extract
-
-
-class Scene(BaseModel):
-    location: str
-    visible_elements: list[str]
-    specifications: dict
-
-
-result = extract(
-    image_path="examples/venice.png",
-    output_schema=Scene,
-    model_config={
-        "model": "gpt-5-mini",
-        "api_key": "sk-...",
-        "temperature": 1,
-    },
-)
-
-print(result.data)
-```
-
-<details>
-<summary>TypeScript</summary>
-
-```ts
-import { images } from "viscribe";
-
-const result = await images.extract({
-  imagePath: "examples/venice.png",
-  outputSchema: {
-    title: "Scene",
-    type: "object",
-    properties: {
-      location: { type: "string" },
-      visible_elements: {
-        type: "array",
-        items: { type: "string" },
-      },
-      specifications: { type: "object" },
-    },
-    required: ["location", "visible_elements", "specifications"],
-    additionalProperties: false,
-  },
-  modelConfig: {
-    model: "gpt-5-mini",
-    apiKey: "sk-...",
-    temperature: 1,
-  },
-});
-
-console.log(result.data);
-```
-
-</details>
-
-> **Note:** `output_schema` can be either a simple list of field definitions or a Pydantic model.
-
-### 5. Compare Images
-
-Compare two images and get a description of their similarities and differences.
-
-```python
-from viscribe.images import compare
-
-result = compare(
-    image1_path="examples/venice.png",
-    image2_path="examples/venice.png",
-    model_config={
-        "model": "gpt-5-mini",
-        "api_key": "sk-...",
-        "temperature": 1,
-    },
-)
-
-print(result.data)
-```
-
-<details>
-<summary>TypeScript</summary>
-
-```ts
-import { images } from "viscribe";
-
-const result = await images.compare({
-  image1Path: "examples/venice.png",
-  image2Path: "examples/venice.png",
-  modelConfig: {
-    model: "gpt-5-mini",
-    apiKey: "sk-...",
-    temperature: 1,
-  },
-});
-
-console.log(result.data);
-```
-
-</details>
-
-## ⚡ Async Usage
-
-All Python endpoints support async operations with direct `a*` helpers:
-
-```python
-import asyncio
-from viscribe.images import adescribe
-
-
-async def main() -> None:
-    result = await adescribe(
-        image_path="examples/venice.png",
-        generate_tags=True,
-        model_config={
-            "model": "gpt-5-mini",
-            "api_key": "sk-...",
-            "temperature": 1,
-        },
-    )
-
-    print(result.data)
-
-
-asyncio.run(main())
-```
-
-You can also reuse an async client:
-
-```python
-import asyncio
-from viscribe import ViscribeAI
+## 🧱 Schema Options
 
+`outputSchema` accepts:
 
-async def main() -> None:
-    client = ViscribeAI(
-        model_config={
-            "model": "gpt-5-mini",
-            "api_key": "sk-...",
-            "temperature": 1,
-        }
-    )
+- simple field definitions
+- JSON Schema objects
 
-    result = await client.images.adescribe(
-        image_path="examples/venice.png",
-        generate_tags=True,
-    )
+Simple field types are `text`, `number`, `array_text`, and `array_number`.
 
-    print(result.data)
-
-
-asyncio.run(main())
-```
-
-<details>
-<summary>TypeScript</summary>
-
-TypeScript is async-native, so use the same methods with `await`:
+## ♻️ Reusable Client
 
 ```ts
-import { images, ViscribeAI } from "viscribe";
-
-const result = await images.describe({
-  imagePath: "examples/venice.png",
-  generateTags: true,
-  modelConfig: {
-    model: "gpt-5-mini",
-    apiKey: "sk-...",
-    temperature: 1,
-  },
-});
-
-console.log(result.data);
+import { ViscribeAI } from "viscribe";
 
 const client = new ViscribeAI({
-  modelConfig: {
-    model: "gpt-5-mini",
-    apiKey: "sk-...",
-    temperature: 1,
-  },
+  modelConfig: { model: "gpt-5-mini", temperature: 1 },
 });
 
-const clientResult = await client.images.describe({
-  imagePath: "examples/venice.png",
-  generateTags: true,
+const result = await client.images.extract({
+  imagePath: "examples/receipt.png",
+  outputSchema: [{ name: "total_amount", type: "number" }],
 });
-
-console.log(clientResult.data);
 ```
 
-</details>
-
-## 📖 Documentation
-
-For detailed documentation, visit [docs.viscribe.ai](https://docs.viscribe.ai)
-
-## 🛠️ Development
-
-For information about setting up the development environment and contributing to the project, see our [Contributing Guide](CONTRIBUTING.md).
-
 ## 💬 Support & Feedback
 
 - 📧 Email: support@viscribe.ai
 - 💻 GitHub Issues: [Create an issue](https://github.com/itsperini/viscribe/issues)
-- 🌟 Feature Requests: [Request a feature](https://github.com/itsperini/viscribe/issues/new)
+- 💬 Discord: [Join the community](https://discord.gg/GVgJ9ujT)
 
 ## 🤝 Contributing
 
-Feel free to contribute and join our Discord server to discuss with us improvements and give us suggestions!
-
-Please see the [contributing guidelines](./CONTRIBUTING.md).
-
-[![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)
-
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+Please see the [contributing guidelines](../CONTRIBUTING.md).
 
-## 🔗 Links
-
-- [Website](https://viscribe.ai)
-- [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). ⭐
-
----
+## 🛠️ Development
 
-Made with ❤️ by [ViscribeAI](https://viscribe.ai)
+```bash
+npm install
+npm test
+npm run typecheck
+npm run build
+npm pack --dry-run
+```