CodeWords Client

Common errors

• HTTP 401 Unauthorized

  cause The CodeWords API key is missing, invalid, or incorrectly formatted in the Authorization header.
  fix Ensure your `CODEWORDS_API_KEY` environment variable is set correctly and the `api_key` argument to `AsyncCodewordsClient` is populated with a valid key. Keys typically start with `cwk-`.

• HTTP 504 Gateway Timeout

  cause A synchronous workflow executed via `client.run()` took longer than the allowed two-minute execution limit.
  fix For workflows that may exceed two minutes, switch to asynchronous execution using `client.run_async()` and then poll for the result with `client.get_result()`.

• KeyError: 'serviceId'

  cause The `service_id` provided to `client.run()` or `client.run_async()` does not correspond to an existing workflow on the CodeWords platform, or there's a typo.
  fix Verify the `service_id` against your deployed workflows in the CodeWords dashboard. Ensure it's correctly specified in your client code.

Warnings

• gotcha Always secure your CodeWords API key. Treat it like a password and store it as an environment variable (e.g., `CODEWORDS_API_KEY`) rather than hardcoding it in your application.
  Fix: Use `os.environ.get('CODEWORDS_API_KEY')` to retrieve your API key. Obtain your API key from the CodeWords account dashboard under the Advanced tab.
• gotcha Choose the correct API endpoint for workflow execution: use `/run` for quick tasks expected to complete under two minutes, and `/run_async` for longer-running operations (up to 30 minutes) to avoid HTTP 504 Gateway Timeout errors.
  Fix: For workflows that might exceed two minutes, use `client.run_async()` to get an immediate request ID, then poll for results using `client.get_result(request_id)`.
• gotcha When troubleshooting workflow issues, remember that `codewords-client` calls interact with the CodeWords platform. Many issues are workflow-specific (e.g., incorrect logic, data transformations) rather than client-library bugs.
  Fix: Utilize the CodeWords platform's built-in debugging tools, including asking 'Cody' (the AI assistant) in the chat interface, reviewing execution logs, and testing with simplified data.

Install

• pip install codewords-client Install stable version

Imports

• AsyncCodewordsClient

  from codewords_client import AsyncCodewordsClient

Quickstart

This quickstart demonstrates how to initialize the CodeWords client with an API key (preferably from an environment variable) and execute both synchronous (`run`) and asynchronous (`run_async`) CodeWords workflows. It also shows a basic polling mechanism to retrieve results from asynchronous operations. Replace `your-sync-workflow-id` and `your-async-workflow-id` with your actual workflow IDs.

import os
import asyncio
from codewords_client import AsyncCodewordsClient

async def run_workflow():
    api_key = os.environ.get('CODEWORDS_API_KEY', 'your_codewords_api_key_here')
    if not api_key or api_key == 'your_codewords_api_key_here':
        print("Please set the CODEWORDS_API_KEY environment variable or replace the placeholder.")
        return

    async with AsyncCodewordsClient(api_key=api_key) as client:
        try:
            # Example: Run a synchronous workflow (for tasks under 2 minutes)
            print("Running synchronous workflow...")
            sync_result = await client.run(
                service_id="your-sync-workflow-id",
                data={
                    "input_param1": "value1",
                    "input_param2": "value2"
                }
            )
            print(f"Synchronous workflow result: {sync_result}")

            # Example: Run an asynchronous workflow (for longer tasks)
            print("Running asynchronous workflow...")
            async_request = await client.run_async(
                service_id="your-async-workflow-id",
                data={
                    "large_data": ["item1", "item2", "..."]
                }
            )
            print(f"Asynchronous workflow initiated. Request ID: {async_request.request_id}")

            # Poll for async result (simplified)
            while True:
                status_response = await client.get_result(async_request.request_id)
                if status_response.status == 'completed':
                    print(f"Async workflow completed. Result: {status_response.result}")
                    break
                elif status_response.status == 'failed':
                    print(f"Async workflow failed. Error: {status_response.error}")
                    break
                else:
                    print(f"Async workflow status: {status_response.status}. Waiting...")
                    await asyncio.sleep(5)

        except Exception as e:
            print(f"An error occurred: {e}")

if __name__ == "__main__":
    asyncio.run(run_workflow())