viscribe 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Viscribe AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,522 @@
+<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>
+
+  <h1>ViscribeAI</h1>
+
+  <p>Extract <strong>structured data</strong> from <strong>images</strong> using <strong>AI models</strong>.</p>
+
+  <p>
+    <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.
+
+## 📦 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
+
+## 🎯 Quick Start
+
+```python
+from viscribe.images import describe
+
+result = describe(
+    image_path="examples/venice.png",
+    # image_base64="...",
+    generate_tags=True,
+    model_config={
+        "model": "gpt-4o-mini",
+        "api_key": "sk-...",
+        "temperature": 0,
+    },
+)
+
+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-4o-mini",
+    apiKey: "sk-...",
+    temperature: 0,
+  },
+});
+
+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
+
+### 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-4o-mini",
+        "api_key": "sk-...",
+        "temperature": 0,
+    },
+)
+
+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-4o-mini",
+    apiKey: "sk-...",
+    temperature: 0,
+  },
+});
+
+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-4o-mini",
+        "api_key": "sk-...",
+        "temperature": 0,
+    },
+)
+
+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-4o-mini",
+    apiKey: "sk-...",
+    temperature: 0,
+  },
+});
+
+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-4o-mini",
+        "api_key": "sk-...",
+        "temperature": 0,
+    },
+)
+
+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-4o-mini",
+    apiKey: "sk-...",
+    temperature: 0,
+  },
+});
+
+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-4o-mini",
+        "api_key": "sk-...",
+        "temperature": 0,
+    },
+)
+
+print(result.data)
+```
+
+<details>
+<summary>TypeScript</summary>
+
+```ts
+import { images } from "viscribe";
+
+const result = await images.extract({
+  imagePath: "examples/venice.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" },
+  ],
+  modelConfig: {
+    model: "gpt-4o-mini",
+    apiKey: "sk-...",
+    temperature: 0,
+  },
+});
+
+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-4o-mini",
+        "api_key": "sk-...",
+        "temperature": 0,
+    },
+)
+
+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-4o-mini",
+    apiKey: "sk-...",
+    temperature: 0,
+  },
+});
+
+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-4o-mini",
+        "api_key": "sk-...",
+        "temperature": 0,
+    },
+)
+
+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-4o-mini",
+    apiKey: "sk-...",
+    temperature: 0,
+  },
+});
+
+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-4o-mini",
+            "api_key": "sk-...",
+            "temperature": 0,
+        },
+    )
+
+    print(result.data)
+
+
+asyncio.run(main())
+```
+
+You can also reuse an async client:
+
+```python
+import asyncio
+from viscribe import ViscribeAI
+
+
+async def main() -> None:
+    client = ViscribeAI(
+        model_config={
+            "model": "gpt-4o-mini",
+            "api_key": "sk-...",
+            "temperature": 0,
+        }
+    )
+
+    result = await client.images.adescribe(
+        image_path="examples/venice.png",
+        generate_tags=True,
+    )
+
+    print(result.data)
+
+
+asyncio.run(main())
+```
+
+<details>
+<summary>TypeScript</summary>
+
+TypeScript is async-native, so use the same methods with `await`:
+
+```ts
+import { images, ViscribeAI } from "viscribe";
+
+const result = await images.describe({
+  imagePath: "examples/venice.png",
+  generateTags: true,
+  modelConfig: {
+    model: "gpt-4o-mini",
+    apiKey: "sk-...",
+    temperature: 0,
+  },
+});
+
+console.log(result.data);
+
+const client = new ViscribeAI({
+  modelConfig: {
+    model: "gpt-4o-mini",
+    apiKey: "sk-...",
+    temperature: 0,
+  },
+});
+
+const clientResult = await client.images.describe({
+  imagePath: "examples/venice.png",
+  generateTags: true,
+});
+
+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)
+
+## 🤝 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/uJN7TYcp)
+[![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.
+
+## 🔗 Links
+
+- [Website](https://viscribe.ai)
+- [Documentation](https://docs.viscribe.ai)
+- [GitHub](https://github.com/itsperini/viscribe)
+
+---
+
+Made with ❤️ by [ViscribeAI](https://viscribe.ai)