amigo_sdk 1.3.0

Amigo AI Python SDK

Amigo Python SDK

The official Python SDK for the Amigo API, providing a simple and intuitive interface to interact with Amigo's AI services.

Installation

This SDK requires Python 3.11 or newer.

Install the SDK using pip:

pip install amigo_sdk

Or add it to your requirements.txt:

amigo_sdk

API compatibility

This SDK auto-generates its types from the latest Amigo OpenAPI schema. As a result, only the latest published SDK version is guaranteed to match the current API. If you pin to an older version, it may not include the newest endpoints or fields.

Quick Start (sync)

from amigo_sdk import AmigoClient
from amigo_sdk.models import GetConversationsParametersQuery

# Initialize and use the client synchronously
with AmigoClient(
    api_key="your-api-key",
    api_key_id="your-api-key-id",
    user_id="user-id",
    organization_id="your-organization-id",
) as client:
    conversations = client.conversation.get_conversations(
        GetConversationsParametersQuery(limit=10, sort_by=["-created_at"])
    )
    print("Conversations:", conversations)

Quick Start (async)

import asyncio

from amigo_sdk import AsyncAmigoClient
from amigo_sdk.models import GetConversationsParametersQuery


async def main():
    async with AsyncAmigoClient(
        api_key="your-api-key",
        api_key_id="your-api-key-id",
        user_id="user-id",
        organization_id="your-organization-id",
    ) as client:
        conversations = await client.conversation.get_conversations(
            GetConversationsParametersQuery(limit=10, sort_by=["-created_at"])
        )
        print("Conversations:", conversations)


asyncio.run(main())

Examples

For more SDK usage examples see the examples overview. Direct links:

• Conversation (sync): examples/conversation/conversation.py
• Conversation (async): examples/conversation/conversation_async.py
• Streaming events: examples/conversation/streaming_events.py
• Async client: examples/conversation/async_client.py
• Error handling: examples/error_handling.py
• User management (sync): examples/user/user-management.py

Configuration

The SDK requires the following configuration parameters:

Parameter	Type	Required	Description
api_key	str	✅	API key from Amigo dashboard
api_key_id	str	✅	API key ID from Amigo dashboard
user_id	str	✅	User ID on whose behalf the request is made
organization_id	str	✅	Your organization ID
base_url	str	❌	Base URL of the Amigo API (defaults to https://api.amigo.ai)

Environment Variables

You can also configure the SDK using environment variables:

export AMIGO_API_KEY="your-api-key"
export AMIGO_API_KEY_ID="your-api-key-id"
export AMIGO_USER_ID="user-id"
export AMIGO_ORGANIZATION_ID="your-organization-id"
export AMIGO_BASE_URL="https://api.amigo.ai"  # optional

Then initialize the client without parameters:

from amigo_sdk import AmigoClient

# Automatically loads from environment variables
with AmigoClient() as client:
    ...

Using .env Files

Create a .env file in your project root:

AMIGO_API_KEY=your-api-key
AMIGO_API_KEY_ID=your-api-key-id
AMIGO_USER_ID=user-id
AMIGO_ORG_ID=your-organization-id

The SDK will automatically load these variables.

Getting Your API Credentials

1. API Key & API Key ID: Generate these from your Amigo admin dashboard or programmatically using the API
2. Organization ID: Found in your Amigo dashboard URL or organization settings
3. User ID: The ID of the user you want to impersonate for API calls

For detailed instructions on generating API keys, see the Authentication Guide.

Available Resources

The SDK provides access to the following resources:

• Organizations: Get Organization info
• Services: Get available services
• Conversation: Manage conversations
• User: Manage users

Generated types

The SDK ships with Pydantic models generated from the latest OpenAPI schema.

• Importing types: Import directly from amigo_sdk.models

  from amigo_sdk.models import (
      GetConversationsParametersQuery,
      ConversationCreateConversationRequest,
      GetUsersParametersQuery,
  )
  

• Using types when calling SDK functions: Pass request/query models to resource methods.

  from amigo_sdk import AmigoClient
  from amigo_sdk.models import GetConversationsParametersQuery
  
  with AmigoClient() as client:
     conversations = client.conversation.get_conversations(
         GetConversationsParametersQuery(limit=20, sort_by=["-created_at"])
     )
  

• Parsing returned objects: Responses are Pydantic models. Access fields directly or convert to dict/JSON.

  # Access fields
  first = conversations.conversations[0]
  print(first.id, first.created_at)
  
  # Convert to plain dict for logging/serialization
  print(first.model_dump(mode="json"))
  

Error Handling

The SDK provides typed error handling:

from amigo_sdk import AmigoClient
from amigo_sdk.errors import (
    AuthenticationError,
    NotFoundError,
    BadRequestError,
    ValidationError,
)

try:
    with AmigoClient() as client:
        org = client.organization.get()
        print("Organization:", org)
except AuthenticationError as error:
    print("Authentication failed:", error)
except NotFoundError as error:
    print("Resource not found:", error)
except BadRequestError as error:
    print("Bad request:", error)
except ValidationError as error:
    print("Validation error:", error)
except Exception as error:
    print("Unexpected error:", error)

Retries

The HTTP client includes sensible, configurable retries:

• Defaults:

  • max attempts: 3
  • backoff base: 0.25s (exponential with full jitter)
  • max delay per attempt: 30s
  • retry on status: {408, 429, 500, 502, 503, 504}
  • retry on methods: {"GET"}
  • special-case: POST is retried on 429 when Retry-After is present
  • 401 triggers a one-time token refresh and immediate retry

Development

For detailed development setup, testing, and contribution guidelines, see CONTRIBUTING.md.

Troubleshooting

Authentication errors

• AuthenticationError: Invalid API key: Verify your api_key and api_key_id are correct and haven't been revoked. Regenerate them from the Amigo dashboard if needed.
• AuthenticationError: Token expired: The SDK refreshes tokens automatically. If this persists, check that your system clock is accurate.

Configuration issues

• ValidationError on client init: Ensure all required fields (api_key, api_key_id, user_id, organization_id) are set either as arguments or environment variables.
• Environment variables not loading: The SDK reads from AMIGO_API_KEY, AMIGO_API_KEY_ID, AMIGO_USER_ID, and AMIGO_ORGANIZATION_ID. Check for typos and that your .env file is in the working directory.

Connection issues

• ConnectionError or timeouts: Check your network connectivity and that https://api.amigo.ai is reachable. If you're behind a proxy, configure it via httpx proxy settings.
• RateLimitError: The SDK retries automatically on 429 responses. If you consistently hit rate limits, reduce request frequency or contact support.

Import errors

• ModuleNotFoundError: No module named 'amigo_sdk': Run pip install amigo_sdk. If using a virtual environment, ensure it is activated.
• Missing model types: The SDK auto-generates types from the OpenAPI spec. Update to the latest version: pip install --upgrade amigo_sdk.

Documentation

• Developer Guide: https://docs.amigo.ai/developer-guide
• API Reference: https://docs.amigo.ai/api-reference

License

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

Support

For questions, issues, or feature requests, please visit our GitHub repository or contact support through the Amigo dashboard.