iq-sdk

A Python SDK for creating and managing distributed workers in IQ Flow orchestration platform.

Quickstart

# Create project directory
mkdir my_iq_tools_project
cd my_iq_tools_project

# Set up virtual environment
python -m venv .venv
source .venv/bin/activate

# Install iq-sdk
pip install iq-sdk

# Initialize project
iq init .

This creates a complete project with configuration, Docker setup, GitHub Actions, and more.

Next steps:

# Set your password in .env
echo "IQ_SITE_DEFAULT_API_SECRET=secret" >> .env

# Create a tool
iq tool add hello

# Run the worker
iq worker run

→ Full Quickstart Guide

Features

• Site-Based Configuration - Manage multiple sites with host/env/user/password
• CLI for Project Scaffolding - Complete setup with iq init
• Socket.IO Worker Connectivity - Workers connect to one or more sites
• Secure Secrets Handling - Passwords via ENV or K8s-style file references
• Configurable Threading - Set thread counts, enable autoscaling
• Docker Integration - Built-in support for baker-cli

Project Structure

After iq init, you get:

my-project/
├── config/
│   └── settings.yml      # Sites and tool configuration
├── .env                  # Secrets (passwords)
├── .gitignore
├── pyproject.toml
├── build-settings.yml    # Docker build config
├── tools/                # Your tool implementations
├── .devcontainer/        # VS Code DevContainer
├── .github/workflows/    # GitHub Actions
└── docker/               # Dockerfile & compose

CLI Reference

Site Management

iq site ls                # List all sites
iq site ls --remote       # Check connectivity
iq site add prod --host http://prod:3000
iq site rm prod

Tool Management

iq tool add NAME          # Create a tool
iq tool ls                # List tools

Worker Management

iq worker ls              # Show configured tools/workers
iq worker ls --remote     # Check tool availability
iq worker run [OPTIONS]   # Start a worker

Options:
  --threads, -t INT      Thread count
  --max-threads INT      Max threads (autoscaling)
  --autoscale            Enable autoscaling
  --tool TOOL            Tools to register (repeatable)
  --site, -s SITE        Sites to connect (repeatable)
  --config, -c FILE      Config file

Output Queue

When task output submission fails (host unreachable, errors), outputs are queued locally for retry:

iq worker queue           # List pending outputs
iq worker queue --failed  # List failed (max retries exceeded)
iq worker queue -t tool   # Filter by tool name
iq worker queue --retry   # Manually retry all pending
iq worker queue --retry -y  # Retry without confirmation

Queue files are stored in ./data/{site}/queue-output/.

Configuration

Sites (config/settings.yml)

site:
  id: "default"
  host: "http://localhost:3000"
  api_key: "worker"
  tools:
    - "my-tool"

sites:
  - id: "production"
    host: "http://prod:3000"
    api_key: "prod-worker"
    tools:
      - "my-tool"

Secrets (.env)

# Direct password
IQ_SITE_DEFAULT_PASSWORD=secret
IQ_SITE_PRODUCTION_PASSWORD=prod-secret

# Or file reference (K8s/Docker secrets)
IQ_SITE_PRODUCTION_API_SECRET_FILE=/run/secrets/prod-password

# For JSON/YAML secrets, extract with _PASSWORD_KEY
IQ_SITE_STAGING_API_SECRET_FILE=/etc/secrets/creds.json
IQ_SITE_STAGING_API_SECRET_KEY=database.password

Worker Settings (config/settings.yml)

worker:
  threads: 2              # Default threads per tool
  autoscale: false        # Enable autoscaling
  min_threads: 1          # Min threads (autoscaling)
  max_threads: 16         # Max threads (autoscaling)

  # Retry settings for failed output submissions
  retry:
    max_retries: 10       # Max retry attempts before moving to failed queue
    initial_delay: 10     # Initial retry delay in seconds
    max_delay: 3600       # Maximum retry delay (1 hour)
    backoff_multiplier: 2.0  # Exponential backoff multiplier

Environment Override

export IQ_SITE_PRODUCTION_HOST='http://new-host:3000'
export IQ_WORKER__THREADS=8
export IQ_WORKER__RETRY__MAX_RETRIES=20

Documentation

• Quickstart - Get started in 5 minutes
• Creating Tools - Build your own tools
• Worker Configuration - Threading and autoscaling
• Site Configuration - Multi-site setup
• Docker Deployment - Container deployment

Development

For contributing or local development:

git clone https://github.com/iq-company/iq-sdk.git
cd iq-sdk
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Test your changes
iq init demo
cd demo

→ Development Guide

License

MIT License - see LICENSE for details.