Python SDK

Official Python SDK for the Girard AI API.

Installation

pip install girardai

Or install from source:

pip install requests

Quick Start

from girardai import Girard AI

client = Girard AI(api_key="your_api_key")

# List workflows
workflows = client.workflows.list()
for workflow in workflows.items:
    print(f"{workflow.name} ({workflow.id})")

# Execute a workflow
result = client.workflows.execute(
    workflow_id="wf_abc123",
    input="Generate a product description",
    variables={"tone": "professional"}
)

if result.success:
    print(result.output)
else:
    print(f"Error: {result.error}")

Configuration

from girardai import Girard AI

client = Girard AI(
    api_key="your_api_key",
    base_url="https://www.girardai.com/api/v1",  # optional
    timeout=30,  # optional, in seconds
)

Workflows

List Workflows

workflows = client.workflows.list(limit=10)

for workflow in workflows.items:
    print(f"{workflow.name} ({workflow.id})")

# Pagination
if workflows.has_more:
    next_page = client.workflows.list(cursor=workflows.next_cursor)

Get a Workflow

workflow = client.workflows.get("wf_abc123")
print(workflow.name)

Create a Workflow

workflow = client.workflows.create(
    name="My Workflow",
    description="A workflow that generates content",
    ai_model="claude-sonnet-4-20250514",
)

Update a Workflow

workflow = client.workflows.update(
    "wf_abc123",
    name="Updated Name",
    is_active=False,
)

Delete a Workflow

client.workflows.delete("wf_abc123")

Execute a Workflow

# Synchronous execution (waits for completion)
result = client.workflows.execute(
    workflow_id="wf_abc123",
    input="Write a blog post about AI",
    variables={
        "topic": "artificial intelligence",
        "length": "medium",
    },
)

if result.success:
    print(f"Output: {result.output}")
    print(f"Tokens used: {result.tokens_used}")
    print(f"Duration: {result.duration_ms}ms")
else:
    print(f"Error: {result.error}")

# Asynchronous execution (returns immediately)
async_result = client.workflows.execute(
    workflow_id="wf_abc123",
    input="Generate content",
    wait=False,
)

print(f"Run ID: {async_result.run_id}")

Runs

Get a Run

run = client.runs.get("run_abc123")
print(run.status)  # PENDING, RUNNING, COMPLETED, FAILED, or CANCELED

List Runs

runs = client.runs.list("wf_abc123", limit=20)

for run in runs.items:
    print(f"{run.id}: {run.status}")

Error Handling

from girardai import (
    Girard AI,
    GirardAIError,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
)

try:
    result = client.workflows.execute(
        workflow_id="wf_abc123",
        input="Generate content",
    )
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except NotFoundError:
    print("Workflow not found")
except GirardAIError as e:
    print(f"API Error: {e.message} ({e.code})")

Type Hints

The SDK includes full type hints for all classes and methods:

from girardai import (
    Workflow,
    WorkflowRun,
    ExecutionResult,
    StepResult,
    RunStatus,
    PaginatedList,
)

def process_workflow(workflow: Workflow) -> None:
    print(workflow.name)

def handle_result(result: ExecutionResult) -> str | None:
    if result.success:
        return result.output
    return None

Requirements

• Python 3.9 or higher
• requests library

License

MIT