Metadata-Version: 2.4
Name: aitronos-freddy
Version: 0.1.1
Summary: Official Python SDK for Freddy AI Assistant API
License: MIT
License-File: LICENSE
Keywords: ai,assistant,api,freddy,llm
Author: Aitronos
Author-email: phillip.loacker@aitronos.com
Requires-Python: >=3.11,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: httpx (>=0.25.0,<0.26.0)
Requires-Dist: pydantic (>=2.9.0,<3.0.0)
Requires-Dist: typing-extensions (>=4.8.0,<5.0.0)
Project-URL: Documentation, https://freddy-api.aitronos.com/docs
Project-URL: Homepage, https://freddy-api.aitronos.com
Project-URL: Repository, https://github.com/aitronos/freddy-python
Description-Content-Type: text/markdown

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

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

