astarcloud 0.1.4

Official Python SDK for the AstarCloud API

AstarCloud SDK

Python SDK for the AstarCloud API with support for chat completions and tool calling.

Installation

pip install astarcloud-sdk

Quick Start

from AstarCloud import AstarClient

client = AstarClient(api_key="sk-...")

# Basic chat completion
response = client.create.completion(
    messages=[{"role": "user", "content": "Hello!"}],
    model="gpt-4.1"
)

print(response.choices[0].message.content)

Tool Calling

The SDK supports tool calling for compatible models (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, astar-gpt-4.1).

Basic Tool Usage

from AstarCloud import AstarClient, ToolSpec

client = AstarClient(api_key="sk-...")

# Define a tool
weather_tool = ToolSpec(
    function={
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    }
)

# Use the tool in a completion
response = client.create.completion(
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
    model="gpt-4.1",
    tools=[weather_tool],
    tool_choice="auto"
)

# Check if the model wants to call a tool
if response.choices[0].tool_calls:
    tool_call = response.choices[0].tool_calls[0]
    print(f"Tool called: {tool_call.function['name']}")
    print(f"Arguments: {tool_call.function['arguments']}")

Bound Tools Client

For convenience, you can create a client with pre-bound tools:

# Create a client with bound tools
bound_client = client.bind_tools([weather_tool])

# All completions will automatically include the bound tools
response = bound_client.create.completion(
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    model="gpt-4.1"
)

Streaming

The SDK supports streaming responses:

for chunk in client.create.completion(
    messages=[{"role": "user", "content": "Write a story"}],
    model="gpt-4.1",
    stream=True
):
    if chunk.choices[0].message.content:
        print(chunk.choices[0].message.content, end="")

Error Handling

from AstarCloud import AstarClient
from AstarCloud._exceptions import APIError, AuthenticationError

try:
    response = client.create.completion(
        messages=[{"role": "user", "content": "Hello"}],
        model="gpt-4.1"
    )
except AuthenticationError:
    print("Invalid API key")
except APIError as e:
    print(f"API error: {e}")

Model Support

Tool-Compatible Models

• gpt-4.1
• gpt-4.1-mini
• gpt-4.1-nano
• astar-gpt-4.1

Other models can be used for basic completions but do not support tool calling.