swarmauri_llm_falai 0.11.0.dev1

Provider-specific Swarmauri import package for fal.ai queue-backed vision-language inference, OCR, image captioning, and visual question answering.

Swarmauri fal.ai Vision Model

swarmauri_llm_falai provides the provider-specific FalAIVisionModel import for Swarmauri projects that call fal.ai vision and image-understanding models. The adapter accepts an image URL plus a prompt, submits the request to fal's queue-backed inference API, polls for completion, and returns the model output string.

This package preserves the legacy LLM-package import path for fal.ai vision workloads while keeping implementation parity with swarmauri_standard.llms.FalAIVisionModel. New VLM-oriented code should also review the newer Swarmauri VLM imports mentioned by the runtime deprecation warning.

fal.ai's public documentation describes queue-backed inference under https://queue.fal.run/{model_id}, including request submission, status polling, and response retrieval. That maps directly to this adapter's predict and apredict workflows.

Why Use This Package?

• Keep fal.ai-specific vision model dependencies isolated from the rest of a Swarmauri application.
• Ask questions about remote images with Swarmauri-style model components.
• Use fal's queue-backed inference lifecycle without writing queue polling logic in application code.
• Preserve compatibility for projects that still import FalAIVisionModel from the LLM provider package.

FAQ

What does swarmauri_llm_falai install?

It installs a provider package that exports FalAIVisionModel from swarmauri_standard.llms.FalAIVisionModel and registers it under the Swarmauri LLM entry point group.

Is this a text-only LLM package?

No. The model accepts image_url and prompt arguments and is intended for vision-language tasks such as OCR, image captioning, visual question answering, and image moderation workflows supported by fal.ai models.

Which fal.ai endpoint does it use?

The adapter posts to https://queue.fal.run/{model_id}. When fal returns a request_id, the adapter polls the corresponding request status endpoint until the request is completed, then fetches the response URL.

Which environment variable can supply credentials?

The model default reads FAL_KEY when api_key is not passed explicitly. The package tests also support live checks when a fal.ai key is available.

Does this adapter support streaming?

No. stream and astream intentionally raise NotImplementedError for FalAIVisionModel.

Features

• Provider-specific FalAIVisionModel import for Swarmauri projects.
• Vision-language prediction with image_url and prompt inputs.
• Queue-backed request submission and status polling through fal.ai.
• Synchronous prediction through predict.
• Asynchronous prediction through apredict.
• Configurable queue polling with max_retries and retry_delay.
• Built-in model allow list covering OCR, LLaVA, Florence, Moondream, MiniCPM, SA2VA, and related fal.ai vision endpoints.
• Compatibility with Python 3.10, 3.11, 3.12, 3.13, and 3.14.

Installation

uv add swarmauri_llm_falai

pip install swarmauri_llm_falai

Prerequisites

Create a fal.ai API key and provide it as FalAIVisionModel(api_key=...) or set FAL_KEY in the runtime environment.

Usage

from swarmauri_llm_falai import FalAIVisionModel

model = FalAIVisionModel(api_key="FAL_KEY")

answer = model.predict(
    image_url="https://llava-vl.github.io/static/images/monalisa.jpg",
    prompt="Who painted this artwork?",
)

print(answer)

Async Vision Question Answering

import asyncio

from swarmauri_llm_falai import FalAIVisionModel


async def main() -> None:
    model = FalAIVisionModel(api_key="FAL_KEY")
    answer = await model.apredict(
        image_url="https://llava-vl.github.io/static/images/monalisa.jpg",
        prompt="Describe the subject of the painting.",
    )
    print(answer)


asyncio.run(main())

Choose A fal.ai Vision Model

from swarmauri_llm_falai import FalAIVisionModel

model = FalAIVisionModel(api_key="FAL_KEY", name="fal-ai/florence-2-large/ocr")

text = model.predict(
    image_url="https://example.com/document-scan.png",
    prompt="Extract the visible text.",
)

print(text)

Related Packages

• swarmauri_llm_deepinfra
• swarmauri_llm_gemini
• swarmauri_llm_openai
• swarmauri_llm_pytesseractimg2text
• swarmauri_llm_whisper

Foundational Swarmauri Packages

• swarmauri_core
• swarmauri_base
• swarmauri_standard
• swarmauri

Provider Documentation

• fal.ai asynchronous inference
• fal.ai synchronous inference
• fal.ai vision models

Best Practices

• Store fal.ai credentials in environment variables or a secrets manager.
• Use image URLs that are reachable by the fal.ai runtime.
• Tune max_retries and retry_delay for long-running queue-backed models.
• Prefer newer Swarmauri VLM imports for new projects when available.

License

Apache-2.0