ViscribeAI Python

Extract structured data from images using AI models.

Define the output schema, pass the image, pick the AI model, and get parsed structured output back instead of free-form text.

📦 Installation

pip install viscribe

🚀 Features

• 🖼️ One schema-driven extract helper for image workflows
• 🔄 Sync and async helpers: extract and aextract
• 📊 Pydantic models, JSON Schema dictionaries, and simple field definitions
• 📁 Local image paths, base64 images, and remote image URLs
• ⚙️ Reusable ViscribeAI().images.extract client namespace
• 🧩 OpenAI-compatible model configuration

🎯 Quick Start

from pydantic import BaseModel, Field
from viscribe.images import extract


class Receipt(BaseModel):
    merchant_name: str | None = Field(description="Store or business name")
    total_amount: float | None = Field(description="Final total on the receipt")
    date: str | None = Field(description="Receipt date if visible")
    line_items: list[str] = Field(description="Visible purchased items")


result = extract(
    image_path="examples/receipt.png",
    output_schema=Receipt,
    instruction="Extract the receipt fields visible in the image.",
    model_config={
        "model": "gpt-5-mini",
        "api_key": "sk-...",
        "temperature": 1,
    },
)

print(result.data.model_dump())

🧱 Schema Options

output_schema accepts:

• simple field definitions
• JSON Schema dictionaries
• Pydantic model classes

Simple field types are text, number, array_text, and array_number.

Strict schemas are checked against the OpenAI Structured Outputs subset before the request is sent. Unsupported schemas raise StructuredOutputSchemaError with the schema path and a suggested fix.

⚡ Async

from viscribe.images import aextract

result = await aextract(
    image_url="https://example.com/receipt.png",
    output_schema=[{"name": "total_amount", "type": "number"}],
    instruction="Extract the visible receipt total.",
)

♻️ Reusable Client

from viscribe import ViscribeAI

client = ViscribeAI(model_config={"model": "gpt-5-mini", "temperature": 1})

result = client.images.extract(
    image_path="examples/receipt.png",
    output_schema=[{"name": "total_amount", "type": "number"}],
)

💬 Support & Feedback

• 📧 Email: support@viscribe.ai
• 💻 GitHub Issues: Create an issue
• 💬 Discord: Join the community

🤝 Contributing

Please see the contributing guidelines.

🛠️ Development

uv sync
uv run ruff check .
uv run python -m pytest
uv build