> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/iii-hq/sdk/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Detailed installation instructions for all III SDK languages

## Prerequisites

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

<Tabs>
  <Tab title="Node.js">
    ### Node.js Requirements

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

    <Tip>
      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.
    </Tip>

    ### Verify Your Installation

    ```bash theme={null}
    node --version  # Should be v20.0.0 or higher
    npm --version   # Any recent version works
    ```
  </Tab>

  <Tab title="Python">
    ### Python Requirements

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

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

    ### Verify Your Installation

    ```bash theme={null}
    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:

    ```bash theme={null}
    # Create a virtual environment
    python -m venv venv

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

    # Activate it (Windows)
    venv\Scripts\activate
    ```
  </Tab>

  <Tab title="Rust">
    ### Rust Requirements

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

    <Tip>
      The III SDK uses the Rust 2024 edition and requires recent language features.
    </Tip>

    ### Verify Your Installation

    ```bash theme={null}
    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:

    ```bash theme={null}
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    ```
  </Tab>
</Tabs>

## III Engine Setup

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

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

```text theme={null}
ws://localhost:49134
```

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

```bash theme={null}
# 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
```

<Note>
  Refer to the III Engine documentation for installation and setup instructions.
</Note>

## Installing the SDK

<Tabs>
  <Tab title="Node.js">
    ### Using npm

    ```bash theme={null}
    npm install iii-sdk
    ```

    ### Using pnpm

    ```bash theme={null}
    pnpm add iii-sdk
    ```

    ### Using yarn

    ```bash theme={null}
    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:

    <CodeGroup>
      ```javascript Main SDK theme={null}
      import { III, getContext } from 'iii-sdk'
      ```

      ```javascript Stream Management theme={null}
      import { Streams } from 'iii-sdk/stream'
      ```

      ```javascript State Management theme={null}
      import { State } from 'iii-sdk/state'
      ```

      ```javascript Telemetry theme={null}
      import { telemetry } from 'iii-sdk/telemetry'
      ```
    </CodeGroup>

    ### TypeScript Configuration

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

    ```json theme={null}
    {
      "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

    <Info>
      All dependencies are automatically installed when you install the SDK.
    </Info>
  </Tab>

  <Tab title="Python">
    ### Using pip

    ```bash theme={null}
    pip install iii-sdk
    ```

    ### Using pip with virtual environment

    ```bash theme={null}
    # 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)

    ```bash theme={null}
    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:

    ```bash theme={null}
    # 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:

    ```bash theme={null}
    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

    <CodeGroup>
      ```python Main SDK theme={null}
      from iii import III
      ```

      ```python Request/Response Models theme={null}
      from iii import ApiRequest, ApiResponse
      ```

      ```python Stream Management theme={null}
      from iii.stream import Streams
      ```

      ```python State Management theme={null}
      from iii.state import State
      ```
    </CodeGroup>

    ### Dependencies

    The SDK requires:

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

    <Info>
      All core dependencies are automatically installed with the SDK.
    </Info>
  </Tab>

  <Tab title="Rust">
    ### Adding to Cargo.toml

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

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

    ### With OpenTelemetry Support

    To enable OpenTelemetry integration:

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

    <Info>
      The `otel` feature includes OpenTelemetry SDK, OTLP exporter, and HTTP client tracing.
    </Info>

    ### 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:

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

    ### Available Imports

    <CodeGroup>
      ```rust Main SDK theme={null}
      use iii_sdk::III;
      ```

      ```rust Stream Management theme={null}
      use iii_sdk::{Streams, UpdateOp, UpdateBuilder};
      ```

      ```rust OpenTelemetry (with otel feature) theme={null}
      use iii_sdk::OtelConfig;
      ```

      ```rust Common Types theme={null}
      use serde_json::json;
      ```
    </CodeGroup>

    ### Building Your Project

    ```bash theme={null}
    # 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

    <Info>
      Cargo automatically downloads and compiles all dependencies when you build your project.
    </Info>
  </Tab>
</Tabs>

## Environment Configuration

### Setting the Engine URL

You can configure the III Engine URL using environment variables:

<CodeGroup>
  ```bash Node.js theme={null}
  export III_BRIDGE_URL=ws://localhost:49134
  # or in your .env file
  III_BRIDGE_URL=ws://localhost:49134
  ```

  ```bash Python theme={null}
  export III_BRIDGE_URL=ws://localhost:49134
  # or in your .env file
  III_BRIDGE_URL=ws://localhost:49134
  ```

  ```bash Rust theme={null}
  export REMOTE_III_URL=ws://127.0.0.1:49134
  # or in your .env file
  REMOTE_III_URL=ws://127.0.0.1:49134
  ```
</CodeGroup>

Then in your code:

<CodeGroup>
  ```javascript Node.js theme={null}
  import { III } from 'iii-sdk'

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

  ```python Python theme={null}
  import os
  from iii import III

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

  ```rust Rust theme={null}
  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);
  ```
</CodeGroup>

## Verifying Installation

Create a simple test to verify your installation:

<CodeGroup>
  ```javascript Node.js theme={null}
  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)
  ```

  ```python Python theme={null}
  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())
  ```

  ```rust Rust theme={null}
  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(())
  }
  ```
</CodeGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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+
  </Accordion>

  <Accordion title="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+
  </Accordion>

  <Accordion title="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`
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Build your first application with the III SDK
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore the complete API documentation
  </Card>

  <Card title="Examples" icon="code" href="https://github.com/iii-hq/sdk">
    Browse complete example applications
  </Card>

  <Card title="Telemetry Setup" icon="chart-line" href="/essentials/telemetry">
    Configure OpenTelemetry for observability
  </Card>
</CardGroup>