aitronos-freddy 0.1.2

Official Python SDK for Freddy AI Assistant API

freddy-python

The official Python SDK for the Freddy API.

Installation

pip install aitronos-freddy

Usage

Prerequisites

Before using the SDK, you need to have:

• A Freddy API Key
• Your Organization ID

You can get these from the Freddy Hub.

Environment Variables

It's recommended to set your credentials as environment variables. You can create a .env file in your project root:

FREDDY_API_KEY="your-api-key-here"
FREDDY_ORG_ID="your-organization-id"

The client will automatically load these variables.

Synchronous Client

Here's a basic example of how to use the synchronous client:

from freddy import FreddyClient

# The client automatically picks up FREDDY_API_KEY from environment variables.
# You can also pass it directly: FreddyClient(api_key="your-key")
with FreddyClient() as client:
    response = client.responses.create(
        model="gpt-4.1",
        inputs=[{"role": "user", "texts": [{"text": "Hello, world!"}]}],
        organization_id="your-org-id" # Can be set via FREDDY_ORG_ID env var
    )
    print(response.output[0].content[0].text)

Asynchronous Client

The SDK also provides an asynchronous client for use with asyncio.

import asyncio
from freddy import AsyncFreddyClient

async def main():
    async with AsyncFreddyClient() as client:
        response = await client.responses.create(
            model="gpt-4.1",
            inputs=[{"role": "user", "texts": [{"text": "Hello, async world!"}]}],
            organization_id="your-org-id"
        )
        print(response.output[0].content[0].text)

if __name__ == "__main__":
    asyncio.run(main())

Development

Setup

1. Clone the repository.

2. Install dependencies using Poetry:

   poetry install
   

Running Tests

The SDK uses pytest.

Unit Tests

These tests don't require any API credentials and are very fast.

poetry run pytest

Integration Tests

These tests run against the actual Freddy API and require credentials. Make sure your .env file is set up as described in the Usage section.

# Run integration tests against the staging environment
poetry run pytest tests/integration/ --integration --env=staging

You can also run against local or production environments by changing the --env flag.

To see test coverage:

poetry run pytest --cov=freddy

Image Operations

The SDK provides comprehensive support for image generation, manipulation, and analysis.

Generate Images

from freddy import FreddyClient

with FreddyClient(api_key="your-api-key") as client:
    result = client.images.generate(
        organization_id="your-org-id",
        prompt="A serene mountain landscape at sunset",
        model="dall-e-3",
        size="1024x1024",
        amount=1
    )
    # Save generated images
    result.save_all("./output")

Upscale Images

result = client.images.upscale(
    organization_id="your-org-id",
    image="photo.jpg",
    target_width=2048,
    target_height=2048
)

Remove Background

result = client.images.remove_background(
    organization_id="your-org-id",
    image="photo.jpg"
)

Replace Background

result = client.images.replace_background(
    organization_id="your-org-id",
    image="photo.jpg",
    prompt="tropical beach with palm trees at sunset"
)

Cleanup (Remove Objects)

result = client.images.cleanup(
    organization_id="your-org-id",
    image="photo.jpg",
    mask="mask.png"  # White areas will be removed
)

Analyze Images

Analyze images using vision-capable AI models. Currently supports GPT-4 and GPT-5 series models.

result = client.images.analyze(
    organization_id="your-org-id",
    image="https://example.com/photo.jpg",  # URL or base64 data URL
    prompt="Describe this image in detail",
    model="gpt-4o-mini"  # Supports: gpt-4o-mini, gpt-4o, gpt-4.1-mini, gpt-5-mini, etc.
)
print(result.output[0].content[0].text)

Note: Claude models are not yet supported for image analysis.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.