# InTouch IML Tool Reference

Authoring an IML tool: the complete field reference — tool metadata, the `credential` block and its `properties`, `input` property types, `steps` and their fields, and `publish` outputs. An IML tool is a self-contained automation unit defined in a single `tool.iml` file; it can be installed, run on demand, used as a task type inside workflows, and invoked by the AI assistant.

## Directory Structure

Each tool lives in its own folder under `tools/installed/`:

```
tools/installed/my-tool/
├── tool.iml           # Tool definition (required)
├── fetch_data.py       # Python scripts (if using python steps)
├── README.md           # Documentation (optional, shown via Help button)
└── help.html           # Custom help page (optional, overrides README)
```

## Tool Definition (`tool.iml`)

```json
{
  "name": "my-tool",
  "displayName": "My Tool",
  "version": "1.0.0",
  "vendor": "Acme Corp",
  "description": "What this tool does",
  "assistantDescription": "",
  "credentialBased": false,
  "maxTime": 0,

  "credential": {
    "properties": {
      "apiKey": {
        "type": "password",
        "description": "API key",
        "required": true
      },
      "server": {
        "type": "string",
        "description": "Server hostname",
        "default": "api.example.com"
      }
    }
  },

  "input": {
    "query": {
      "type": "string",
      "required": true,
      "description": "Search query"
    },
    "maxResults": {
      "type": "number",
      "default": "10",
      "description": "Maximum results to return"
    },
    "verbose": {
      "type": "boolean",
      "default": "false"
    }
  },

  "steps": [
    {
      "name": "step-one",
      "type": "http",
      "output": { "myField": "$.data.value" }
    },
    {
      "name": "step-two",
      "type": "python"
    }
  ],

  "publish": {
    "result": "{{step-one.myField}}",
    "detail": "{{step-two.parsed}}"
  }
}
```

IML is JSON, so it carries no inline comments. What each field means:

| Field | Meaning |
|---|---|
| `name` | Unique lowercase name (**required**) |
| `displayName` | Human-friendly name shown in the UI |
| `assistantDescription` | If set, the AI assistant can invoke this tool directly |
| `credentialBased` | `true` if the tool needs credentials (API keys, DB logins, …) |
| `maxTime` | Max execution time in seconds (`0` = unlimited) |
| `credential` | Only present when `credentialBased` is `true` |
| `input` | Parameters supplied at runtime |
| `steps` | Execution steps, run in order; each step's `output` extracts values from its response |
| `publish` | Final tool outputs, available to downstream tasks |

For a long-form note inside a definition, use the top-level `comment` field — an array of
strings — rather than trying to comment a line.

### Input Property Types

| Type | Description | Example Default |
|------|-------------|-----------------|
| `string` | Text value | `"hello"` |
| `password` | Secret text (masked in UI) | — |
| `number` | Numeric value | `"10"` |
| `boolean` | true/false | `"false"` |

---

## Variable Resolution

Variables are resolved before each step executes.

| Syntax | Source | Example |
|--------|--------|---------|
| `{{input.name}}` | Input parameter | `{{input.query}}` |
| `{{credential.name}}` | Credential property | `{{credential.apiKey}}` |
| `{{stepName.field}}` | Output from a prior step | `{{fetch.body}}` |
| `{{env.VAR_NAME}}` | Environment variable | `{{env.HOME}}` |

The special input `{{input._skillDir}}` is automatically injected — it contains the absolute path to the tool's install directory. Useful for Python scripts that need to access files bundled with the tool.

---

## Step Types

### http

Makes an HTTP request.

```json
[
  {
    "name": "call-api",
    "type": "http",
    "method": "GET",
    "url": "https://api.example.com/data?q={{input.query}}",
    "contentType": "application/json",
    "body": "{\"key\": \"value\"}",
    "headers": {
      "X-Custom": "value"
    },
    "auth": {
      "type": "bearer",
      "token": "{{credential.apiKey}}"
    },
    "successCodes": [
      200,
      201
    ],
    "output": {
      "status": "$._status",
      "body": "$._body",
      "value": "$.data.items[0].name"
    }
  }
]
```

**Auto-outputs:** `_status`, `_body`

**JSONPath support:** `$.field`, `$.field.subfield`, `$.array[0]`, `$[*].field`

---

### python

Runs a Python script bundled with the tool.

```json
[
  {
    "name": "process-data",
    "type": "python",
    "script": "my_script.py",
    "args": "{{input.tickers}}",
    "workingDir": "/tmp",
    "timeout": 60,
    "successExitCodes": [
      0
    ],
    "output": {
      "parsed": "$.result"
    }
  }
]
```

**How it works:**
1. InTouch writes a temp JSON context file containing `input`, `credential`, and `steps` data
2. Runs: `python3 <script> <context_file_path> <args>`
3. Your script's first argument is the context file path, remaining args are from `args`
4. Script should print JSON to stdout for structured output
5. Context file is deleted after execution

**Auto-outputs:** `_stdout`, `_stderr`, `_exitCode`, plus all top-level keys from JSON stdout

**Example Python script:**
```python
import json, sys

# Read context (input, credential, prior step outputs)
with open(sys.argv[1]) as f:
    ctx = json.load(f)

tickers = sys.argv[2] if len(sys.argv) > 2 else ctx["input"].get("tickers", "")

# Do work...
result = {"status": "ok", "data": "..."}

# Print JSON to stdout — keys become step outputs
print(json.dumps(result))
```

---

### sql

Runs a SQL query against a database credential.

```json
[
  {
    "name": "query-db",
    "type": "sql",
    "query": "SELECT name, price FROM products WHERE category = '{{input.category}}'",
    "credentialName": "my-database",
    "output": {
      "firstProduct": "$.rows[0].name"
    }
  }
]
```

**Auto-outputs:** `_columns` (comma-separated), `_rowCount`, `_rows` (JSON array, max 10,000 rows), plus each column from the first row as individual outputs

---

### shell

Runs a shell command.

```json
[
  {
    "name": "check-disk",
    "type": "shell",
    "command": "df -h /data | tail -1 | awk '{print $5}'",
    "workingDir": "/tmp",
    "timeout": 30,
    "successExitCodes": [
      0
    ],
    "output": {
      "usage": "$._stdout"
    }
  }
]
```

**Auto-outputs:** `_stdout`, `_stderr`, `_exitCode`

Runs via `/bin/sh -c` on Linux, `cmd /c` on Windows.

---

### ai

Sends a prompt to an AI provider and gets a response.

```json
[
  {
    "name": "analyze",
    "type": "ai",
    "provider": "anthropic",
    "prompt": "Analyze this data: {{fetch.body}}",
    "systemPrompt": "You are a data analyst.",
    "output": {
      "analysis": "$.answer"
    }
  }
]
```

**Auto-outputs:** `answer`, `model`, `inputTokens`, `outputTokens`

---

### file

File system operations.

```json
[
  {
    "name": "read-config",
    "type": "file",
    "operation": "read",
    "path": "/etc/myapp/config.json"
  },
  {
    "name": "save-results",
    "type": "file",
    "operation": "write",
    "path": "/tmp/results.json",
    "content": "{{process.output}}"
  },
  {
    "name": "backup",
    "type": "file",
    "operation": "copy",
    "path": "/data/current.db",
    "destination": "/backups/current.db.bak"
  },
  {
    "name": "archive",
    "type": "file",
    "operation": "move",
    "path": "/tmp/report.csv",
    "destination": "/archive/report.csv"
  },
  {
    "name": "cleanup",
    "type": "file",
    "operation": "delete",
    "path": "/tmp/scratch.txt"
  },
  {
    "name": "check",
    "type": "file",
    "operation": "exists",
    "path": "/data/input.csv"
  }
]
```

---

### transform

String transformations on a value.

```json
[
  {
    "name": "clean-response",
    "type": "transform",
    "source": "{{fetch.body}}",
    "expression": "uppercase",
    "output": {
      "cleaned": "$.result"
    }
  }
]
```

**Expressions:**

| Expression | Description | Example |
|------------|-------------|---------|
| `uppercase` | Convert to uppercase | `hello` → `HELLO` |
| `lowercase` | Convert to lowercase | `HELLO` → `hello` |
| `trim` | Trim whitespace | `" hi "` → `"hi"` |
| `length` | String length | `"hello"` → `"5"` |
| `replace:old->new` | Replace substring | `replace:foo->bar` |
| `regex:pattern` | First regex match | `regex:\d+` |
| `substring:start,end` | Extract substring | `substring:0,5` |
| `split:delimiter` | Split and join with newlines | `split:,` |
| `contains:search` | Case-insensitive contains check | `contains:error` |

**Output:** `result`

---

### condition

Conditional branching.

```json
[
  {
    "name": "check-status",
    "type": "condition",
    "condition": "{{call-api.status}} == 200",
    "thenSteps": [
      {
        "name": "log-ok",
        "type": "log",
        "message": "API returned OK"
      }
    ],
    "elseSteps": [
      {
        "name": "log-fail",
        "type": "log",
        "message": "API failed with {{call-api.status}}"
      }
    ]
  }
]
```

**Condition operators:** `==`, `!=`, `>`, `<`, `>=`, `<=`

Supports numeric and string comparison. Non-empty strings are truthy. Literals `true`/`false` work.

---

### loop

Iterate over a list of items.

```json
[
  {
    "name": "check-hosts",
    "type": "loop",
    "items": "{{input.hosts}}",
    "itemVar": "host",
    "loopSteps": [
      {
        "name": "ping",
        "type": "http",
        "method": "GET",
        "url": "http://{{check-hosts.host}}/health"
      }
    ]
  }
]
```

**Loop variables available inside loopSteps:**
- `{{loopStepName.itemVar}}` — current item value
- `{{loopStepName.index}}` — current index (0-based)
- `{{loopStepName.count}}` — total item count

---

### log

Posts a message to the activity log.

```json
[
  {
    "name": "status-update",
    "type": "log",
    "message": "Processed {{query.rowCount}} rows",
    "level": "info"
  }
]
```

---

### sleep

Pauses execution.

```json
[
  {
    "name": "wait",
    "type": "sleep",
    "duration": 5
  }
]
```

**Output:** `_slept` (seconds actually slept)

---

## Error Handling

Each step has an `onError` property:

| Value | Behavior |
|-------|----------|
| `fail` | Stop execution, tool fails (default) |
| `skip` | Skip this step, continue to next |
| `continue` | Log warning, continue to next |

```json
[
  {
    "name": "optional-step",
    "type": "http",
    "onError": "skip",
    "url": "https://optional-api.example.com/data"
  }
]
```

---

## Publishing Output

The `publish` section maps tool outputs from step results:

```json
{
  "publish": {
    "analysis": "{{sentiment.analysis}}",
    "rawData": "{{fetch-data.data}}",
    "status": "{{call-api.status}}"
  }
}
```

Published properties are available:
- In the tool run results
- As `{{toolTaskName.propertyName}}` when this tool is used as a task inside an IML workflow
- As published workflow properties when run as a workflow task

---

## Writing Output to a File

Use a `file` step with `operation: write`:

```json
{
  "steps": [
    {
      "name": "fetch-data",
      "type": "http",
      "url": "https://api.example.com/data",
      "output": {
        "body": "$._body"
      }
    },
    {
      "name": "save-to-file",
      "type": "file",
      "operation": "write",
      "path": "/tmp/output.json",
      "content": "{{fetch-data.body}}"
    }
  ]
}
```

You can make the output path an input parameter:

```json
{
  "input": {
    "outputFile": {
      "type": "string",
      "required": false,
      "default": "",
      "description": "Write results to this file (optional)"
    }
  },
  "steps": [
    {
      "name": "save-output",
      "type": "condition",
      "condition": "{{input.outputFile}}",
      "thenSteps": [
        {
          "name": "write-file",
          "type": "file",
          "operation": "write",
          "path": "{{input.outputFile}}",
          "content": "{{process.result}}"
        }
      ]
    }
  ]
}
```

---

## Complete Example: REST API Monitor

```json
{
  "name": "rest-monitor",
  "displayName": "REST API Monitor",
  "version": "1.0.0",
  "description": "Checks an HTTP endpoint and reports status",
  "assistantDescription": "Monitor a REST API endpoint \u2014 checks status and response time",
  "input": {
    "url": {
      "type": "string",
      "required": true,
      "description": "URL to monitor"
    },
    "expectedStatus": {
      "type": "string",
      "default": "200",
      "description": "Expected HTTP status code"
    }
  },
  "steps": [
    {
      "name": "check",
      "type": "http",
      "method": "GET",
      "url": "{{input.url}}",
      "successCodes": [
        200,
        201,
        301,
        302,
        404,
        500
      ],
      "output": {
        "status": "$._status",
        "body": "$._body"
      }
    },
    {
      "name": "evaluate",
      "type": "condition",
      "condition": "{{check.status}} == {{input.expectedStatus}}",
      "thenSteps": [
        {
          "name": "log-ok",
          "type": "log",
          "message": "{{input.url}} returned {{check.status}} \u2014 OK"
        }
      ],
      "elseSteps": [
        {
          "name": "log-fail",
          "type": "log",
          "message": "{{input.url}} returned {{check.status}} \u2014 EXPECTED {{input.expectedStatus}}",
          "level": "warn"
        }
      ]
    }
  ],
  "publish": {
    "url": "{{input.url}}",
    "status": "{{check.status}}",
    "body": "{{check.body}}"
  }
}
```

---

## Installation

Three ways to install an IML tool:

1. **File system:** Copy the tool folder to `tools/installed/` and restart (or call reload)
2. **UI:** Hub Tools view → paste IML content → Install
3. **REST API:** `POST /api/intouch-tool/install-iml` with `{"content": "<iml>"}`
4. **AI Assistant:** Ask it to create a tool — it uses `create_iml_tool`

---

## IML Tools vs IML Workflows

| | IML Tool | IML Workflow |
|---|---|---|
| **What it is** | A reusable building block | A workflow that chains tools |
| **Variable syntax** | `{{name.field}}` (same as workflows; plus `{{input.x}}`/`{{credential.x}}`) | `{{name.field}}` |
| **Input** | Parameterized (different each run) | Hardcoded in IML |
| **Steps/Tasks** | Steps (http, python, sql, etc.) | Tasks (any registered tool) |
| **Credential** | Own credential schema | Per-task named credentials |
| **Schedulable** | Only as a task within a workflow | Yes — convert to workflow, attach schedule |
| **AI Assistant** | Yes (via `assistantDescription`) | Via `create_iml_workflow` |
| **Install location** | `tools/installed/{name}/` | `workflows/iml/` |
| **Reusable** | Yes — callable from any workflow | No — one-off workflow |