Skip to content

amigo-ai/amigo-python-sdk

Repository files navigation

Amigo banner

amigo_sdk

Official Python SDK for the Classic Amigo API.

Product Docs · Developer Guide · API Reference · Examples · Changelog

PyPI version CI codecov MIT License

Synchronous and asynchronous Python clients for the original org-scoped Amigo backend at api.amigo.ai, with generated Pydantic models from the committed OpenAPI snapshot, typed errors, and NDJSON conversation streaming.

Classic Backend Context

amigo_sdk targets the original org-scoped Amigo backend. Existing deployments still use this surface for conversations, services, organizations, users, agents, context graphs, webhooks, and streaming events.

Classic text session flow

Product Status

amigo_sdk remains the supported Python client for the Classic API.

The Platform API is where new workspace-scoped capabilities land first, but the Classic API is not being switched off abruptly. Amigo will publish a migration path, compatibility notes, and upgrade guidance before asking customers to move production workloads.

Choose The Right Surface

If you need Start here
Existing org-scoped integrations on api.amigo.ai from Python amigo_sdk
New workspace-scoped integrations on api.platform.amigo.ai Platform API docs today. A first-party Python migration path will follow as platform-native coverage expands

Documentation

Need Best entry point
Product overview and deployment context docs.amigo.ai
Integration guidance and developer docs Developer Guide
Generated API reference amigo-ai.github.io/amigo-python-sdk
Runnable examples examples/
Release history CHANGELOG.md

The docs site remains the primary reference. The repo-local examples stay close to the shipped package surface and the published package is validated in CI.

Installation

Python 3.11+ is required.

pip install amigo_sdk

Quick Start

Sync Client

from amigo_sdk import AmigoClient
from amigo_sdk.models import GetConversationsParametersQuery

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.conversations.get_conversations(
        GetConversationsParametersQuery(limit=10, sort_by=["-created_at"])
    )
    print(conversations.conversations[0].id if conversations.conversations else None)

Async Client

import asyncio

from amigo_sdk import AsyncAmigoClient
from amigo_sdk.models import GetConversationsParametersQuery


async def main() -> None:
    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.conversations.get_conversations(
            GetConversationsParametersQuery(limit=10, sort_by=["-created_at"])
        )
        print(len(conversations.conversations))


asyncio.run(main())

Configuration

Option Type Required Description
api_key str Yes API key from the Amigo dashboard
api_key_id str Yes API key ID paired with api_key
user_id str Yes User ID on whose behalf the request is made
organization_id str Yes Organization ID for the classic API
base_url str No Override the API base URL. Defaults to https://api.amigo.ai

Environment variables are also supported:

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"

Generated Models

The SDK ships with generated Pydantic models and exposes them from amigo_sdk.models:

from amigo_sdk.models import (
    ConversationCreateConversationRequest,
    GetConversationsParametersQuery,
)

Public builds are generated from the committed specs/openapi-baseline.json snapshot in this repo so generated models stay deterministic across machines and CI runs. Refresh that snapshot before regenerating models:

sync-openapi
gen-models

Error Handling

from amigo_sdk import AmigoClient
from amigo_sdk.errors import AuthenticationError, NotFoundError, RateLimitError

try:
    with AmigoClient() as client:
        organization = client.organizations.get()
        print(organization.id)
except AuthenticationError as error:
    print("Authentication failed:", error)
except NotFoundError as error:
    print("Resource not found:", error)
except RateLimitError as error:
    print("Rate limited:", error)

Support

Use the issue tracker for bugs and feature requests. For responsible disclosure, see SECURITY.md.

About

Official Python SDK for the Classic Amigo API at api.amigo.ai

Topics

Resources

License

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Packages

 
 
 

Contributors