Metadata-Version: 2.4
Name: fastn-sdk
Version: 0.1.1
Summary: Python SDK for Fastn Automation Platform
Home-page: https://github.com/fastnai/fastn-python-sdk
Author: Fastn AI
Author-email: support@fastn.ai
Keywords: fastn,automation,ai,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: certifi>=2020.12.5
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Fastn SDK for Python

[![PyPI version](https://img.shields.io/pypi/v/fastn-sdk.svg)](https://pypi.org/project/fastn-sdk/)
[![Python versions](https://img.shields.io/pypi/pyversions/fastn-sdk.svg)](https://pypi.org/project/fastn-sdk/)
[![License](https://img.shields.io/pypi/l/fastn-sdk.svg)](https://github.com/fastnai/fastn-python-sdk/blob/main/LICENSE)

The official Python SDK for the Fastn Automation Platform, providing a seamless interface for leveraging AI to automate tasks across various integrated services.

## Installation

```bash
pip install fastn-sdk
```

## Quick Start

```python
import os
from fastn import FastnClient

async def main():
    # Initialize with your API credentials
    client = FastnClient(
        api_key=os.environ.get("FASTN_API_KEY"),
        space_id=os.environ.get("FASTN_SPACE_ID")
    )
    
    # Execute an action with a natural language prompt
    try:
        response = await client.execute_action(
            prompt="Send a Slack message to #general saying Hello from Fastn SDK!",
            session_id="user_session_123"  # Optional: For conversation context
        )
        print(f"Success: {response}")
    except Exception as e:
        print(f"Error: {e}")

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

## Features

- **Natural Language Interface**: Use plain English to describe your automation tasks
- **Multiple Service Integration**: Access Slack, Google Calendar, Gmail, HubSpot, and more from a single API
- **Session Management**: Maintain context across multiple API calls
- **Comprehensive Error Handling**: Detailed error information and recovery guidance
- **Debug Mode**: Enable detailed logging for development and troubleshooting

## Authentication

Obtain your API credentials (API key and space ID) from your Fastn account dashboard. Store these securely and never commit them to version control.

## Usage Examples

### Basic Usage

```python
from fastn import FastnClient

client = FastnClient(
    api_key="your_api_key", 
    space_id="your_space_id"
)

async def schedule_meeting():
    response = await client.execute_action(
        prompt="Schedule a team meeting for tomorrow at 3pm"
    )
    return response
```

### Using Session ID for Context

```python
from fastn import FastnClient

client = FastnClient(
    api_key="your_api_key", 
    space_id="your_space_id"
)

async def process_emails():
    # First request
    response1 = await client.execute_action(
        prompt="Find emails from John about the project timeline",
        session_id="user123"
    )
    
    # Follow-up request with context from the first
    response2 = await client.execute_action(
        prompt="Reply to the most recent one saying I'll review it today",
        session_id="user123"  # Same session ID maintains context
    )
    
    return response1, response2
```

### Debug Mode

```python
from fastn import FastnClient

client = FastnClient(
    api_key="your_api_key",
    space_id="your_space_id"
)

async def create_contact():
    # Enable debug mode to see detailed request/response information
    response = await client.execute_action(
        prompt="Create a contact in HubSpot for jane@example.com",
        debug=True
    )
    return response
```

### Custom Environment

```python
from fastn import FastnClient

# Optional configuration for custom environments
client = FastnClient(
    api_key="your_api_key",
    space_id="your_space_id",
    tenant_id="optional_tenant_id",
    base_url="https://live.fastn.ai"  # Defaults to production endpoint
)

async def perform_action():
    response = await client.execute_action(prompt="Your prompt here")
    return response
```

## Error Handling

The SDK includes a dedicated `FastnAPIError` exception with detailed information about API errors:

```python
from fastn import FastnClient
from fastn.sdk import FastnAPIError

client = FastnClient(
    api_key="your_api_key",
    space_id="your_space_id"
)

async def handle_errors():
    try:
        response = await client.execute_action(prompt="Your prompt here")
        return response
    except FastnAPIError as e:
        print(f"Status code: {e.status_code}")
        print(f"Error message: {e}")
        print(f"Error details: {e.error_data}")
        
        # Handle specific error codes
        if e.status_code == 401:
            print("Check your API credentials")
        elif e.status_code == 429:
            print("Rate limited, try again later")
```

## Supported Actions

The Fastn SDK supports operations across multiple services:

### Slack
- Send messages
- Get channels
- Get users in a channel

### Google Calendar
- Create meetings
- Get events

### Gmail
- Send emails
- Get messages

### HubSpot
- Create, update, and delete contacts
- Create and manage deals
- Create companies
- Add notes and engagements

And many more! The flexibility of natural language prompts means you can describe virtually any action supported by integrated services.

## Common Troubleshooting

- **401 Unauthorized**: Verify your API key and space ID
- **429 Too Many Requests**: You've exceeded the rate limits, try again later
- **400 Bad Request**: The prompt may be unclear or missing key information
- **503 Service Unavailable**: The service is temporarily unavailable

## License

This SDK is distributed under the MIT license. See the LICENSE file for more information.

## Support

For assistance, visit our [documentation](https://docs.fastn.ai) or contact [support@fastn.ai](mailto:support@fastn.ai). 
