aitronos-freddy 0.1.2
Official Python SDK for Freddy AI Assistant API
License: MIT
Requires Python: <4.0,>=3.11
Keywords: ai, assistant, api, freddy, llm

# freddy-python

The official Python SDK for the Freddy API.

## Installation

```bash
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](https://freddy-hub.aitronos.com/freddy/api).

### 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:

```python
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`.

```python
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:

    ```bash
    poetry install
    ```

### Running Tests

The SDK uses `pytest`.

**Unit Tests**

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

```bash
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](#usage) section.

```bash
# 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:
```bash
poetry run pytest --cov=freddy
```

## Image Operations

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

### Generate Images

```python
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

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

### Remove Background

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

### Replace Background

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

### Cleanup (Remove Objects)

```python
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.

```python
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](LICENSE) file for details.