Installation - III SDK

Prerequisites

Before installing the III SDK, ensure you have the following prerequisites for your chosen language:

Node.js
Python
Rust

Node.js Requirements

Node.js: Version 20 or higher
Package Manager: npm, pnpm, or yarn
TypeScript (optional): Version 5.9+ for TypeScript projects

The III SDK for Node.js is published as an ES module with TypeScript types included. It works seamlessly with both JavaScript and TypeScript projects.

Verify Your Installation

node --version  # Should be v20.0.0 or higher
npm --version   # Any recent version works

Python Requirements

Python: Version 3.10 or higher
pip: Latest version recommended
Virtual Environment (recommended): venv or virtualenv

The III SDK requires Python 3.10+ due to its use of modern async features and type hints.

Verify Your Installation

python --version  # Should be 3.10 or higher
pip --version     # Any recent version works

Setting Up a Virtual Environment

It’s recommended to use a virtual environment to avoid dependency conflicts:

# Create a virtual environment
python -m venv venv

# Activate it (Linux/macOS)
source venv/bin/activate

# Activate it (Windows)
venv\Scripts\activate

Rust Requirements

Rust: Version 1.85 or higher (2024 edition)
Cargo: Included with Rust installation
Tokio: The SDK uses Tokio for async runtime

The III SDK uses the Rust 2024 edition and requires recent language features.

Verify Your Installation

rustc --version  # Should be 1.85.0 or higher
cargo --version  # Any recent version works

Installing Rust

If you don’t have Rust installed, use rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

III Engine Setup

The III SDK requires a running III Engine instance to function. Make sure the engine is running before starting your application.

The III Engine should be running and accessible via WebSocket. By default, the engine runs on:

ws://localhost:49134

You can verify the engine is running by checking if the WebSocket endpoint is accessible:

# Using websocat (install with: cargo install websocat)
websocat ws://localhost:49134

# Or using wscat (install with: npm install -g wscat)
wscat -c ws://localhost:49134

Refer to the III Engine documentation for installation and setup instructions.

Installing the SDK

Node.js
Python
Rust

Using npm

npm install iii-sdk

Using pnpm

pnpm add iii-sdk

Using yarn

yarn add iii-sdk

Package Information

Package Name: iii-sdk
Current Version: 0.4.1
Registry: npm
License: Apache-2.0

Available Exports

The Node.js SDK provides multiple entry points:

import { III, getContext } from 'iii-sdk'

import { Streams } from 'iii-sdk/stream'

import { State } from 'iii-sdk/state'

import { telemetry } from 'iii-sdk/telemetry'

TypeScript Configuration

The SDK includes TypeScript definitions. Ensure your tsconfig.json is configured for ES modules:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true
  }
}

Dependencies

The SDK includes the following key dependencies:

ws - WebSocket client
@opentelemetry/* - OpenTelemetry packages for observability

All dependencies are automatically installed when you install the SDK.

Using pip

pip install iii-sdk

Using pip with virtual environment

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the SDK
pip install iii-sdk

Using uv (faster alternative)

uv pip install iii-sdk

Package Information

Package Name: iii-sdk
Current Version: 0.4.1
Registry: PyPI
License: Apache-2.0

Optional Dependencies

The SDK supports optional OpenTelemetry integration:

# Install with OpenTelemetry support
pip install iii-sdk[otel]

This installs:

opentelemetry-api
opentelemetry-sdk

Development Dependencies

If you’re contributing to the SDK or running tests:

pip install iii-sdk[dev]

This installs additional tools:

pytest - Testing framework
pytest-asyncio - Async test support
mypy - Type checking
ruff - Linting and formatting

Available Imports

from iii import III

from iii import ApiRequest, ApiResponse

from iii.stream import Streams

from iii.state import State

Dependencies

The SDK requires:

websockets >= 12.0 - WebSocket client
pydantic >= 2.0 - Data validation

All core dependencies are automatically installed with the SDK.

Adding to Cargo.toml

Add the III SDK to your project’s Cargo.toml:

[dependencies]
iii-sdk = "0.4.1"
tokio = { version = "1", features = ["full"] }
serde_json = "1"

With OpenTelemetry Support

To enable OpenTelemetry integration:

[dependencies]
iii-sdk = { version = "0.4.1", features = ["otel"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"

The otel feature includes OpenTelemetry SDK, OTLP exporter, and HTTP client tracing.

Package Information

Crate Name: iii-sdk
Current Version: 0.4.1
Registry: crates.io (when published)
License: Apache-2.0
Rust Edition: 2024
MSRV: 1.85

Available Features

The Rust SDK provides the following features:

Feature	Description	Default
`default`	Core SDK functionality	✅
`otel`	OpenTelemetry integration	❌

Required Dependencies

The SDK requires these Tokio features at minimum:

[dependencies]
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Available Imports

use iii_sdk::III;

use iii_sdk::{Streams, UpdateOp, UpdateBuilder};

use iii_sdk::OtelConfig;

use serde_json::json;

Building Your Project

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run your application
cargo run

# Run tests
cargo test

Dependencies Included

The SDK automatically includes:

tokio-tungstenite - WebSocket client
serde / serde_json - Serialization
async-trait - Async trait support
tracing - Logging framework

Cargo automatically downloads and compiles all dependencies when you build your project.

Environment Configuration

Setting the Engine URL

You can configure the III Engine URL using environment variables:

export III_BRIDGE_URL=ws://localhost:49134
# or in your .env file
III_BRIDGE_URL=ws://localhost:49134

export III_BRIDGE_URL=ws://localhost:49134
# or in your .env file
III_BRIDGE_URL=ws://localhost:49134

export REMOTE_III_URL=ws://127.0.0.1:49134
# or in your .env file
REMOTE_III_URL=ws://127.0.0.1:49134

Then in your code:

import { III } from 'iii-sdk'

const iii = new III(process.env.III_BRIDGE_URL ?? 'ws://localhost:49134')

import os
from iii import III

iii = III(os.getenv("III_BRIDGE_URL", "ws://localhost:49134"))

use iii_sdk::III;

let iii_url = std::env::var("REMOTE_III_URL")
    .unwrap_or("ws://127.0.0.1:49134".into());
let iii = III::new(&iii_url);

Verifying Installation

Create a simple test to verify your installation:

import { III } from 'iii-sdk'

const iii = new III('ws://localhost:49134')

iii.registerFunction({ id: 'test.ping' }, () => {
  return { status_code: 200, body: { message: 'pong' } }
})

const result = await iii.call('test.ping', {})
console.log('✅ Installation successful:', result)

import asyncio
from iii import III

async def test_ping(data):
    return {"message": "pong"}

iii = III("ws://localhost:49134")
iii.register_function("test.ping", test_ping)

async def main():
    await iii.connect()
    result = await iii.call("test.ping", {})
    print("✅ Installation successful:", result)

asyncio.run(main())

use iii_sdk::III;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let iii = III::new("ws://127.0.0.1:49134");
    iii.connect().await?;

    iii.register_function("test.ping", |_| async move {
        Ok(json!({ "message": "pong" }))
    });

    let result: serde_json::Value = iii.call("test.ping", json!({})).await?;
    println!("✅ Installation successful: {}", result);
    Ok(())
}

Troubleshooting

Connection refused or timeout errors

This usually means the III Engine is not running or not accessible.Solutions:

Verify the engine is running: Check the engine process is active
Check the URL: Ensure you’re using the correct WebSocket URL
Check firewall: Ensure port 49134 is not blocked
Check network: If using Docker, ensure proper network configuration

Module not found errors (Node.js)

This can happen with ES module configuration.Solutions:

Ensure your package.json includes "type": "module"
Use .mjs file extension for ES modules
Check your Node.js version is 20+

Import errors (Python)

This can happen with virtual environment or Python path issues.Solutions:

Activate your virtual environment
Verify installation: pip show iii-sdk
Reinstall: pip install --force-reinstall iii-sdk
Check Python version: python --version should be 3.10+

Compilation errors (Rust)

This can happen with Rust version or dependency issues.Solutions:

Update Rust: rustup update
Check Rust version: rustc --version should be 1.85+
Clean build: cargo clean && cargo build
Update dependencies: cargo update

OpenTelemetry errors

Issues with telemetry exports or configuration.Solutions:

Verify OpenTelemetry collector is running (if using one)
Check OTLP endpoint configuration
Disable telemetry temporarily to isolate the issue
Check environment variables for OTEL configuration

Next Steps

Quickstart Guide

Build your first application with the III SDK

API Reference

Explore the complete API documentation

Examples

Browse complete example applications

Telemetry Setup

Configure OpenTelemetry for observability

​Prerequisites

​Node.js Requirements

​Verify Your Installation

​Python Requirements

​Verify Your Installation

​Setting Up a Virtual Environment

​Rust Requirements

​Verify Your Installation

​Installing Rust

​III Engine Setup

​Installing the SDK

​Using npm

​Using pnpm

​Using yarn

​Package Information

​Available Exports

​TypeScript Configuration

​Dependencies

​Using pip

​Using pip with virtual environment

​Using uv (faster alternative)

​Package Information

​Optional Dependencies

​Development Dependencies

​Available Imports

​Dependencies

​Adding to Cargo.toml

​With OpenTelemetry Support

​Package Information

​Available Features

​Required Dependencies

​Available Imports

​Building Your Project

​Dependencies Included

​Environment Configuration

​Setting the Engine URL

​Verifying Installation

​Troubleshooting

​Next Steps

Quickstart Guide

API Reference

Examples

Telemetry Setup

Prerequisites

Node.js Requirements

Verify Your Installation

Python Requirements

Verify Your Installation

Setting Up a Virtual Environment

Rust Requirements

Verify Your Installation

Installing Rust

III Engine Setup

Installing the SDK

Using npm

Using pnpm

Using yarn

Package Information

Available Exports

TypeScript Configuration

Dependencies

Using pip

Using pip with virtual environment

Using uv (faster alternative)

Package Information

Optional Dependencies

Development Dependencies

Available Imports

Dependencies

Adding to Cargo.toml

With OpenTelemetry Support

Package Information

Available Features

Required Dependencies

Available Imports

Building Your Project

Dependencies Included

Environment Configuration

Setting the Engine URL

Verifying Installation

Troubleshooting

Next Steps