Skip to content

feat: FalAI integration #190

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
iRubeel wants to merge 11 commits into
base: main
Choose a base branch
from
Open

feat: FalAI integration #190

iRubeel wants to merge 11 commits into from

Conversation

@iRubeel
Copy link
Contributor

@iRubeel iRubeel commented Dec 11, 2025 •
edited
Loading

Summary

This PR adds comprehensive fal.ai integration to BubbleLab, enabling users to generate and transform images using fal.ai's media generation APIs. The integration includes four operations (text-to-image, image-to-image, status checking, and result retrieval) with full async polling support, error handling, and UI integration.

Related Issues

Closes #175

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Refactor
  • Other (please describe):

Checklist

  • My code follows the code style of this project
  • I have added appropriate tests for my changes
  • I have run pnpm check and all tests pass
  • I have tested my changes locally
  • I have linked relevant issues
  • I have added screenshots for UI changes (if applicable)

Screenshots (if applicable)

FalAI Logo in Integrations Section

image

Credential Card

image

Fal AI Bubble

image

Additional Context

Files Changed:

  • New files:

    • packages/bubble-core/src/bubbles/service-bubble/fal-ai.ts - Main implementation
    • packages/bubble-core/src/bubbles/service-bubble/fal-ai.test.ts - Unit tests (28 tests)
    • apps/bubble-studio/public/integrations/fal-ai.png - Logo file

  • Modified files:

    • packages/bubble-core/src/bubble-factory.ts - Bubble registration
    • packages/bubble-core/src/index.ts - Exports
    • packages/bubble-shared-schemas/src/types.ts - CredentialType and BubbleName
    • packages/bubble-shared-schemas/src/credential-schema.ts - Credential mappings
    • packages/bubble-shared-schemas/src/bubble-definition-schema.ts - Bubble config
    • apps/bubblelab-api/src/services/credential-validator.ts - Backend validation
    • apps/bubble-studio/src/pages/CredentialsPage.tsx - Frontend UI
    • apps/bubble-studio/src/lib/integrations.ts - Logo configuration

iRubeel and others added 6 commits December 10, 2025 21:49
@iRubeel
feat(fal-ai): add fal.ai integration for media generation
f237a1c 
- Implement FalAiBubble with 4 operations (text_to_image, image_to_image, get_status, get_result)
- Add async polling with exponential backoff for long-running jobs
- Configure credential management (FAL_AI_API_KEY) in backend and frontend
- Add logo integration and UI configuration
- Include 28 unit tests covering all operations and error cases
- Add type safety with Zod schemas and TypeScript types

Closes bubblelabai#175
@iRubeel
Merge branch 'bubblelabai:main' into feat/fal-ai-integration
c47be4e
@iRubeel
style: fix trailing whitespace in fal-ai.ts
cb051d2
@iRubeel
fixing ui for falai
1b3eb48
@iRubeel
frontend FalAi fix
6bb8585
@iRubeel
Merge branch 'bubblelabai:main' into feat/fal-ai-integration
86a4a93
Copilot AI review requested due to automatic review settings December 11, 2025 07:04
@bubblelab-pearl
Copy link
Contributor

bubblelab-pearl commented Dec 11, 2025

Suggested PR title from Pearl

Title: feat(fal-ai): add Fal AI integration for media generation

Body:
This PR introduces a new service integration for Fal AI, enabling media generation capabilities within the platform.

The FalAiBubble allows for:

  • Text-to-image generation: Create images from textual prompts using various Fal AI models (e.g., Flux, Stable Diffusion).
  • Image-to-image transformation: Modify existing images based on new prompts.
  • Asynchronous job management: Support for checking job status and retrieving results for long-running operations, including automatic polling with exponential backoff.

Key changes include:

  • bubble-core: Implementation of the FalAiBubble with Zod schemas for parameters and results, API interaction logic, and credential handling.
  • bubble-studio: Integration of Fal AI into the UI, including adding its logo, aliases, and a dedicated credential type (FAL_AI_API_KEY) for users to manage their API keys.
  • bubblelab-api: Backend validation logic for Fal AI API keys.
  • bubble-shared-schemas: Definition of the new CredentialType.FAL_AI_API_KEY and its association with the fal-ai bubble.
  • Tests: Comprehensive unit tests for the FalAiBubble covering all operations, error handling, and polling logic.

Copilot AI reviewed Dec 11, 2025
View reviewed changes
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adds comprehensive fal.ai integration to BubbleLab, enabling users to generate and transform images using fal.ai's media generation APIs. The integration implements four operations (text-to-image, image-to-image, status checking, and result retrieval) with full async polling support, proper error handling, and complete UI integration including logo assets and credential management.

Key Changes

  • Implemented FalAiBubble service with text-to-image, image-to-image, status checking, and result retrieval operations
  • Added async polling with exponential backoff for long-running image generation tasks
  • Integrated fal.ai credentials into the credential management system with validation support
  • Added UI components including logo, credential cards, and service branding

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 13 comments.

Show a summary per file
File Description
packages/bubble-core/src/bubbles/service-bubble/fal-ai.ts Main bubble implementation with 4 operations, polling logic, and error handling
packages/bubble-core/src/bubbles/service-bubble/fal-ai.test.ts Comprehensive test suite with 28 tests covering all operations and edge cases
packages/bubble-core/src/bubble-factory.ts Registered fal-ai bubble in factory and exports
packages/bubble-core/src/index.ts Exported FalAiBubble class and type definitions
packages/bubble-shared-schemas/src/types.ts Added FAL_AI_API_KEY credential type and fal-ai bubble name
packages/bubble-shared-schemas/src/credential-schema.ts Added credential mappings and bubble credential options
packages/bubble-shared-schemas/src/bubble-definition-schema.ts Added credential configuration
apps/bubblelab-api/src/services/credential-validator.ts Added validation parameters for fal.ai credentials
apps/bubble-studio/src/pages/CredentialsPage.tsx Added UI configuration for fal.ai credentials
apps/bubble-studio/src/lib/integrations.ts Added logo mappings and regex patterns
apps/bubble-studio/public/integrations/fal-ai.png Added fal.ai logo asset

packages/bubble-core/src/bubbles/service-bubble/fal-ai.ts
'Current status of the request (IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED)'
),
success: z.boolean().describe('Whether the status check was successful'),
error: z.string().describe('Error message if the status check failed'),
Copy link

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The error field description says "Error message if the status check failed", but since the field is required (not optional), it would be clearer to describe it as "Error message (empty string if successful)".

Suggested change
error: z.string().describe('Error message if the status check failed'),
error: z.string().describe('Error message (empty string if successful)'),

Copilot uses AI. Check for mistakes.
packages/bubble-core/src/bubbles/service-bubble/fal-ai.ts
success: z
.boolean()
.describe('Whether the result retrieval was successful'),
error: z.string().describe('Error message if the result retrieval failed'),
Copy link

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The error field description says "Error message if the result retrieval failed", but since the field is required (not optional), it would be clearer to describe it as "Error message (empty string if successful)".

Suggested change
error: z.string().describe('Error message if the result retrieval failed'),
error: z.string().describe('Error message (empty string if successful)'),

Copilot uses AI. Check for mistakes.
packages/bubble-core/src/bubbles/service-bubble/fal-ai.ts Outdated
static readonly schema = FalAiParamsSchema;
static readonly resultSchema = FalAiResultSchema;
static readonly shortDescription =
'Fal AI integration for media generation (text-to-image, image-to-image)';
Copy link

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The shortDescription uses "Fal AI" but the service name is "fal.ai" (with a dot and lowercase). For consistency with the official service name and the API URL, consider using "fal.ai" instead.

Suggested change
'Fal AI integration for media generation (text-to-image, image-to-image)';
'fal.ai integration for media generation (text-to-image, image-to-image)';

Copilot uses AI. Check for mistakes.
packages/bubble-core/src/bubbles/service-bubble/fal-ai.ts Outdated
static readonly shortDescription =
'Fal AI integration for media generation (text-to-image, image-to-image)';
static readonly longDescription = `
Integrate with Fal AI's media generation APIs for creating and transforming images.
Copy link

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The longDescription uses "Fal AI's" but the service name is "fal.ai" (with a dot and lowercase). For consistency with the official service name, consider using "fal.ai's" instead.

Suggested change
Integrate with Fal AI's media generation APIs for creating and transforming images.
Integrate with fal.ai's media generation APIs for creating and transforming images.

Copilot uses AI. Check for mistakes.
packages/bubble-core/src/bubbles/service-bubble/fal-ai.ts
.string()
.min(1, 'Model is required')
.describe(
'Fal AI model ID (e.g., "fal-ai/flux/dev", "fal-ai/stable-diffusion-v1-5")'
Copy link

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The description uses "Fal AI model ID" but the service name is "fal.ai". For consistency, consider using "fal.ai model ID" instead.

Suggested change
'Fal AI model ID (e.g., "fal-ai/flux/dev", "fal-ai/stable-diffusion-v1-5")'
'fal.ai model ID (e.g., "fal-ai/flux/dev", "fal-ai/stable-diffusion-v1-5")'

Copilot uses AI. Check for mistakes.
packages/bubble-core/src/bubbles/service-bubble/fal-ai.ts Outdated
- fal-ai/flux/dev - Fast, high-quality image generation
- fal-ai/stable-diffusion-v1-5 - Classic Stable Diffusion
- fal-ai/flux/schnell - Ultra-fast generation
- And many more (check Fal AI docs for full list)
Copy link

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The longDescription references "Fal AI docs" but the service name is "fal.ai". For consistency with the official service name, consider using "fal.ai docs" instead.

Suggested change
- And many more (check Fal AI docs for full list)
- And many more (check fal.ai docs for full list)

Copilot uses AI. Check for mistakes.
packages/bubble-core/src/bubbles/service-bubble/fal-ai.ts
model: z
.string()
.min(1, 'Model is required')
.describe('Fal AI model ID for image-to-image (e.g., "fal-ai/flux/dev")'),
Copy link

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The description uses "Fal AI model ID" but the service name is "fal.ai". For consistency, consider using "fal.ai model ID" instead.

Suggested change
.describe('Fal AI model ID for image-to-image (e.g., "fal-ai/flux/dev")'),
.describe('fal.ai model ID for image-to-image (e.g., "fal-ai/flux/dev")'),

Copilot uses AI. Check for mistakes.
packages/bubble-core/src/bubbles/service-bubble/fal-ai.ts Outdated
return {
operation: 'text_to_image',
success: false,
error: 'Fal AI API key is required',
Copy link

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The error message uses "Fal AI API key is required" but the tests expect "fal.ai API key is required". The error messages should be consistent with what the tests expect. Consider using "fal.ai API key is required" to match the service's actual name as shown in the API base URL.

Suggested change
error: 'Fal AI API key is required',
error: 'fal.ai API key is required',

Copilot uses AI. Check for mistakes.
packages/bubble-core/src/bubbles/service-bubble/fal-ai.ts Outdated
operation: 'get_status',
status: 'FAILED',
success: false,
error: 'Fal AI API key is required',
Copy link

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The error message uses "Fal AI API key is required" but the tests expect "fal.ai API key is required". The error messages should be consistent with what the tests expect.

Suggested change
error: 'Fal AI API key is required',
error: 'fal.ai API key is required',

Copilot uses AI. Check for mistakes.
packages/bubble-core/src/bubbles/service-bubble/fal-ai.ts
'Status of the request (IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED)'
),
success: z.boolean().describe('Whether the operation was successful'),
error: z.string().describe('Error message if the operation failed'),
Copy link

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The error field description says "Error message if the operation failed", but since the field is required (not optional), it would be clearer to describe it as "Error message (empty string if successful)".

Copilot uses AI. Check for mistakes.
@zhubzy
Copy link
Contributor

zhubzy commented Dec 12, 2025

@iRubeel Thank you so much for this, I will take a closer look sometime tommorw and review

zhubzy
zhubzy requested changes Dec 15, 2025
View reviewed changes
Copy link
Contributor

@zhubzy zhubzy left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@iRubeel Thank you so much for this! A few things:

Could you add the model discovery route: https://docs.fal.ai/platform-apis/v1/models
we are pushing changes to allow dynamic context gathering for pearl and this would help tremendously for pearl to find and use these model correctly.

  1. Should have search operation to find availble models based on query(that can find model ie veo3 to find the google model),
  2. Should have list opeartion which should contain openapi schema and some basic details (see offocial doc, they support this)
  3. For each of the operations, could you attach a screenshot of it succesfully running on bubble studio (if you need credit let us know)
  4. Could you fix the unit test that is failing?

@iRubeel
Copy link
Contributor Author

iRubeel commented Dec 18, 2025 •
edited
Loading

Thanks for the feedback @zhubzy! Here's the complete status update.

Added Model Discovery Route

Implemented all operations from https://docs.fal.ai/platform-apis/v1/models

  • Search Operation - Find models by query (e.g., "veo3" → Google Veo 3)
  • List Operation - Returns OpenAPI schema + all metadata
  • Get Model Operation (Bonus) - Retrieve specific model(s) by ID

1. Search Operation

image

2. Added List Operation Containing Openapi schema and basic details

image

3. Fixed the initial unit test failure

@iRubeel iRubeel changed the title Integrating FalAI feat: FalAI integration Jan 10, 2026
@iRubeel iRubeel requested a review from zhubzy February 4, 2026 06:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@zhubzy zhubzy Awaiting requested review from zhubzy

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

fal.ai Integration

3 participants

@iRubeel @bubblelab-pearl @zhubzy