Python SDK

Async-first Python client with type hints, Pydantic models, and built-in support for streaming responses.

View on GitHub

Installation

Install the SDK using pip:

pip install taskforceai-python

Requires Python 3.8 or higher.

Quick Start

Initialize the client and run a task:

from
taskforceai
import
TaskForceAIClient

client = TaskForceAIClient(api_key=
"your-api-key"
)

task_id = client.submit_task(
"Analyze the security posture of this repository."
)
result = client.wait_for_completion(task_id)

print(result[
"result"
])

Basic Usage

Use run_task to submit and wait for completion in one call:

# Submit and wait for result in one call

result = client.run_task(
"What is the capital of France?"
)
print(result[
"result"
])

# Or use options for more control

task_id = client.submit_task(
"Complex analysis task"
,
model_id=
"xai/grok-4.1"
,
options={
"silent"
: True}
)
result = client.wait_for_completion(task_id)

Async Usage

Use the async client for better performance in async applications:

import
asyncio
from
taskforceai
import
AsyncTaskForceAIClient

async def
main():
async with
AsyncTaskForceAIClient(api_key=
"your-api-key"
)
as
client:
result =
await
client.run_task(
"Summarize the latest updates"
)
print(result[
"result"
])

asyncio.run(main())

Streaming Status Updates

Stream task status updates in real-time:

# Stream status updates as task progresses

stream = client.run_task_stream(
"Analyze this codebase"
)

for
status
in
stream:
print(f
"{status['status']}: {status.get('result')}"
)

# Cancel locally if needed

# stream.cancel()

Configuration Options

ParameterTypeDescription
api_keystrYour TaskForceAI API key (required)
base_urlstrCustom API endpoint URL
timeoutintRequest timeout in seconds
max_retriesintMaximum number of retry attempts
mock_modeboolEnable mock mode for local development (default: False)

Mock Mode

Build and test your integration without an API key using mock mode:

from
taskforceai
import
TaskForceAIClient

# No API key required in mock mode

client = TaskForceAIClient(mock_mode=
True
)

result = client.run_task(
"Test your integration"
)
print(result.result)
# "This is a mock response. Configure your API key to get real results."

Mock mode simulates the full task lifecycle locally—no network requests are made.

Type Hints & Pydantic Models

The SDK uses Pydantic models and provides full type hints for better IDE support:

from
taskforceai
import
TaskForceAIClient
from
taskforceai.types
import
TaskSubmissionOptions

client = TaskForceAIClient(api_key=
"your-key"
)

options: TaskSubmissionOptions = {
"model_id"
:
"xai/grok-4.1"
,
"silent"
: True
}

# Fully typed response model

result = client.run_task(
"Hello!"
, options=options)

Next Steps