### Install the watsonx.ai CLI

Source: https://www.ibm.com/watsonx/developer/agents/quickstart

Install the command-line interface tool required for managing watsonx.ai agents.

```bash
pip install ibm-watsonx-ai-cli
```

--------------------------------

### Install Dependencies for watsonx.ai

Source: https://www.ibm.com/watsonx/developer/capabilities/time-series

Install the required Python packages for time series forecasting.

```python
1!pip install wget | tail -n 1
2!pip install -U matplotlib | tail -n 1
3!pip install -U ibm-watsonx-ai | tail -n 1
```

--------------------------------

### Model response with tool call

Source: https://www.ibm.com/watsonx/developer/capabilities/tool-calling

Example of the JSON response returned by the model when it determines a tool should be called.

```json
{
  "id": "chat-a00942a130e84f83bc0090c38c2f419f",
  "model_id": "mistralai/mistral-large",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "chatcmpl-tool-77cbe4e94d88489383a0c6ed1b644674",
            "type": "function",
            "function": {
              "name": "add",
              "arguments": "{\"a\": 2, \"b\": 4}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}
```

--------------------------------

### Text extraction response structure

Source: https://www.ibm.com/watsonx/developer/capabilities/text-extraction

Example of the JSON response returned after a successful text extraction submission.

```json
{
  "metadata": {
    "id": "6213cf1-252f-424b-b52d-5cdd9814956c",
    "created_at": "2023-05-02T16:27:51Z",
    "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f",
    "name": "extract"
  },
  "entity": {
    "document_reference": {
      "type": "connection_asset",
      "connection": {
        "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d"
      },
      "location": {
        "file_name": "files/document.pdf"
      }
    },
    "results_reference": {
      "type": "connection_asset",
      "connection": {
        "id": "2a7c11bc-2913-48d0-9581-a8d9f40fa159"
      },
      "location": {
        "file_name": "results"
      }
    },
    "steps": {
      "tables_processing": {
        "enabled": true
      }
    },
    "results": {
      "status": "submitted",
      "number_pages_processed": 0
    }
  }
}
```

--------------------------------

### Configure the agent project

Source: https://www.ibm.com/watsonx/developer/agents/quickstart

Navigate to the project directory and prepare the configuration file.

```bash
cd langgraph-arxiv-research
cp config.toml.example config.toml
```

--------------------------------

### Initialize an agent template

Source: https://www.ibm.com/watsonx/developer/agents/quickstart

Create a new agent project from available templates.

```bash
watsonx-ai template new
```

--------------------------------

### Execute prompt tuning with data connections

Source: https://www.ibm.com/watsonx/developer/capabilities/model-tuning

Run the prompt tuning process using different types of data references, such as S3 locations, data assets, or container locations.

```python
from ibm_watsonx_ai.helpers import DataConnection, ContainerLocation, S3Location

tuning_details = prompt_tuner.run(
    training_data_references=[DataConnection(
        connection_asset_id=connection_id,
        location=S3Location(
            bucket='prompt_tuning_data',
            path='pt_train_data.json'
        )
    )],
    background_mode=False)

# OR

tuning_details = prompt_tuner.run(
    training_data_references=[DataConnection(
        data_asset_id='5d99c11a-2060-4ef6-83d5-dc593c6455e2')
    ],
    background_mode=True)

# OR

tuning_details = prompt_tuner.run(
    training_data_references=[DataConnection(
        location=ContainerLocation("path_to_file.json"))
    ],
    background_mode=True)
```

--------------------------------

### Configure PromptTuner in watsonx.ai

Source: https://www.ibm.com/watsonx/developer/capabilities/model-tuning

Initialize the TuneExperiment and configure the prompt tuner with specific model parameters and task settings.

```python
from ibm_watsonx_ai import Credentials
from ibm_watsonx_ai.experiment import TuneExperiment

credentials = Credentials(
  url = "{watsonx_ai_url}",
  apikey = "{apikey}",
)

experiment = TuneExperiment(
    credentials=Credentials(...),
    project_id = "{project_id}"
    space_id="{space_id}")

prompt_tuner = experiment.prompt_tuner(
    name="prompt tuning name",
    task_id=experiment.Tasks.CLASSIFICATION,
    base_model=ModelTypes.FLAN_T5_XL,
    accumulate_steps=32,
    batch_size=16,
    learning_rate=0.2,
    max_input_tokens=256,
    max_output_tokens=2,
    num_epochs=6,
    tuning_type=experiment.PromptTuningTypes.PT,
    verbalizer="Extract the satisfaction from the comment. Return simple '1' for satisfied customer or '0' for unsatisfied. Input: {{input}} Output: ",
    auto_update_model=True
)
```

--------------------------------

### Deploy and test the agent service

Source: https://www.ibm.com/watsonx/developer/agents/quickstart

Deploy the agent to IBM Cloud and verify the service deployment.

```bash
watsonx-ai service new
```

```bash
watsonx-ai service invoke 'Hello, how can you help me?'
```

--------------------------------

### List Available Foundation Models (cURL)

Source: https://www.ibm.com/watsonx/developer/get-started/models

Use this cURL command to retrieve a list of all foundation models, including Tech Preview models, available in your watsonx.ai account. Replace `{token}` and `{watsonx_ai_url}` with your specific credentials.

```shell
curl -X GET \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
"{watsonx_ai_url}/ml/v1/foundation_model_specs?version=2024-05-31&tech_preview=true"
```

--------------------------------

### Import Energy Dataset

Source: https://www.ibm.com/watsonx/developer/capabilities/time-series

Download and load the energy demand CSV file into a pandas DataFrame.

```python
1import os, wget
2import pandas as pd
3
4filename = 'energy_dataset.csv'
5base_url = 'https://github.com/IBM/watson-machine-learning-samples/raw/refs/heads/master/cloud/data/energy/'
6
7if not os.path.isfile(filename): wget.download(base_url + filename)
8
9df = pd.read_csv(filename)
```

--------------------------------

### Generate text using the Node.js SDK

Source: https://www.ibm.com/watsonx/developer

This Node.js code snippet demonstrates how to initialize the WatsonXAI SDK and generate text. Replace the placeholder for project_id.

```javascript
const { WatsonXAI } = require('@ibm-cloud/watsonx-ai');

const watsonxAIService = WatsonXAI.newInstance();

const textGeneration = watsonxAIService.generateText({
  input: 'How far is Paris from Bangalore?',
  modelId: 'ibm/granite-13b-instruct-v2',
  projectId: '{project_id}'
});
```

--------------------------------

### Initialize model inference with Python SDK

Source: https://www.ibm.com/watsonx/developer

This Python code snippet shows how to initialize the ModelInference class from the watsonx.ai Python SDK. Replace the placeholder for project_id.

```python
from ibm_watsonx_ai.foundation_models import ModelInference

model = ModelInference(
  model_id="ibm/granite-13b-instruct-v2",
  project_id="{project_id}"
)

prompt = 'How far is Paris from Bangalore?'


```

--------------------------------

### Generate text using the watsonx.ai API

Source: https://www.ibm.com/watsonx/developer/capabilities/text-generation

Use a POST request to prompt the granite-13b-instruct-v2 model. Replace placeholders with your specific token, URL, and project ID.

```curl
curl -X POST \
-H 'Authorization: Bearer {token}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
  "input": "How far is Paris from Bangalore?",
  "parameters": {
    "max_new_tokens": 100,
    "time_limit": 10000
  },
  "model_id": "ibm/granite-13b-instruct-v2",
  "project_id": "{project_id}"
}' \
"{watsonx_ai_url}/ml/v1/text/generation?version=2024-05-31"
```

--------------------------------

### List Available Time Series Models

Source: https://www.ibm.com/watsonx/developer/capabilities/time-series

Retrieve and print specifications for available time series foundation models.

```python
1for model in client.foundation_models.get_time_series_model_specs()["resources"]:
2    print('--------------------------------------------------')
3    print(f'model_id: {model["model_id"]}')
4    print(f'functions: {model["functions"]}')
5    print(f'long_description: {model["long_description"]}')
6    print(f'label: {model["label"]}')
```

--------------------------------

### Enable Streaming with Node.js SDK

Source: https://www.ibm.com/watsonx/developer/capabilities/chat

This Node.js code snippet demonstrates how to enable streaming for text generation using the watsonx.ai SDK. It iterates over the streamed response and logs each line.

```javascript
try {
  watsonxAIService.generateTextStream(params).then(async (res) => {
    for await (const line of res) {
      console.log(line);
    }
  });
} catch (err) {
  console.warn(err);
}
```

--------------------------------

### Inspect Dataset

Source: https://www.ibm.com/watsonx/developer/capabilities/time-series

Display statistical summary and tail rows of the loaded dataset.

```python
1df.describe() # Describe the data
2
3df.tail() # Show the last few rows of the dataset
```

--------------------------------

### Enable default content filters in Python

Source: https://www.ibm.com/watsonx/developer/capabilities/text-generation

Apply default guardrail settings to text generation requests in the Python library.

```python
response = model.generate(prompt,guardrails=True)
```

--------------------------------

### Initialize TSModelInference

Source: https://www.ibm.com/watsonx/developer/capabilities/time-series

Initialize the TSModelInference class, a wrapper for watsonx.ai models, by providing the model ID and API client.

```python
from ibm_watsonx_ai.foundation_models import TSModelInference

ts_model = TSModelInference(
    model_id=ts_model_id,
    api_client=client
)
```

--------------------------------

### Run AutoAI RAG Experiment

Source: https://www.ibm.com/watsonx/developer/capabilities/autoai-rag

Use this code to schedule an AutoAI RAG experiment. Ensure that `input_data_references`, `test_data_references`, and `results_connection` are properly configured. Set `background_mode=True` to run the experiment asynchronously.

```python
run_details = rag_optimizer.run(
    input_data_references=[input_data_connection],
    test_data_references=[test_data_connection],
    results_reference=results_connection,
    background_mode=True
)
```

--------------------------------

### Generate text with tool calling via cURL

Source: https://www.ibm.com/watsonx/developer/capabilities/tool-calling

Sends a POST request to the chat endpoint with a defined tool and user message. Replace placeholders with your specific authentication token, URL, and project ID.

```bash
curl -X POST \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
"{watsonx_ai_url}/ml/v1/text/chat?version=2024-05-31" \
--data-raw '{
    "model_id": "mistralai/mistral-large",
    "project_id": "{project_id}",
    "messages": [{
        "role": "user",
        "content": [{
            "type": "text",
            "text": "What is 2 plus 4?"
        }]
    }],
    "tools": [{
        "type": "function",
        "function": {
            "name": "add",
            "description": "Adds the values a and b to get a sum.",
            "parameters": {
                "type": "object",
                "properties": {
                    "a": {
                        "description": "A number value",
                        "type": "number"
                    },
                    "b": {
                        "description": "A number value",
                        "type": "number"
                    }
                },
                "required": [
                    "a",
                    "b"
                ]
            }
        }
    }],
    "tool_choice_option": "auto",
    "max_tokens": 300,
    "time_limit": 1000
  }'
```

--------------------------------

### Invoke the agent locally

Source: https://www.ibm.com/watsonx/developer/agents/quickstart

Run the agent locally to test functionality via the terminal.

```bash
watsonx-ai template invoke "show me the latest arxiv papers on the model context protocol"
```

--------------------------------

### Send a Chat Message using cURL

Source: https://www.ibm.com/watsonx/developer/capabilities/chat

Use this cURL command to send a structured list of messages to a foundation model for a chat interaction. Replace placeholders like {token}, {watsonx_ai_url}, and {project_id} with your specific details.

```curl
curl -X POST \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
"{watsonx_ai_url}/ml/v1/text/chat?version=2024-05-31" \
--data-raw '{
    "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "How far is Paris from Bangalore?"
        }
      ]
    },
    {
      "role": "assistant",
      "content": "The distance between Paris, France, and Bangalore, India, is approximately 7,800 kilometers (4,850 miles)"
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the flight distance?"
        }
      ]
    }
  ],
  "parameters": {
    "max_new_tokens": 100,
    "time_limit": 10000
  },
  "model_id": "meta-llama/llama-3-2-3b-instruct",
  "project_id": "{project_id}"}'
```

--------------------------------

### Third-Party Foundation Models

Source: https://www.ibm.com/watsonx/developer/get-started/models

Information on foundation models provided by third-party vendors, including their capabilities and pricing.

```APIDOC
## Third-Party Foundation Models

### SDAIA ALLaM

Model Name| Model ID| Max Tokens| Input Price (per 1K tokens)| Output Price (per 1K tokens)  
---|---|---|---|---
allam-1-13b-instruct| `sdaia/allam-1-13b-instruct`| 4,096| $0.0018| $0.0018  

### Code Llama

Model Name| Model ID| Max Tokens| Input Price (per 1K tokens)| Output Price (per 1K tokens)  
---|---|---|---|---
codellama-34b-instruct| `codellama/codellama-34b-instruct-hf`| 16,384| $0.0018| $0.0018  

### Other Third-Party Models

Model| Model ID| Text Generation| Chat Completion| Tool Calling| Vision  
---|---|---|---|---|---
flan-t5-xl-3b| `google/flan-t5-xl`| ✅| ✅| |
flan-t5-xxl-11b| `google/flan-t5-xxl`| ✅| ✅| |
flan-ul2-20b| `google/flan-ul2`| ✅| ✅| |
llama-4-maverick-17b-128e-instruct-fp8| `meta-llama/llama-4-maverick-17b-128e-instruct-fp8`| ✅| ✅| ✅|
llama-4-scout-17b-16e-instruct Beta| `meta-llama/llama-4-scout-17b-16e-instruct`| ✅| ✅| ✅|
llama-3-3-70b-instruct| `meta-llama/llama-3-3-70b-instruct`| ✅| ✅| ✅|
llama-3-2-1b-instruct| `meta-llama/llama-3-2-1b-instruct`| ✅| ✅| |
llama-3-2-3b-instruct| `meta-llama/llama-3-2-3b-instruct`| ✅| ✅| |
llama-3-2-11b-vision-instruct| `meta-llama/llama-3-2-11b-vision-instruct`| ✅| ✅| ✅| ✅
llama-3-2-90b-vision-instruct| `meta-llama/llama-3-2-90b-vision-instruct`| ✅| ✅| ✅| ✅
llama-guard-3-11b-vision-instruct| `meta-llama/llama-guard-3-11b-vision`| ✅| ✅| ✅| ✅
llama-3-1-8b-instruct (Deprecated)| `meta-llama/llama-3-1-8b-instruct`| ✅| ✅| |
llama-3-1-70b-instruct (Deprecated)| `meta-llama/llama-3-1-70b-instruct`| ✅| ✅| |
llama-2-13b-chat (Deprecated)| `meta-llama/llama-2-13b-chat`| ✅| ✅| |
mistral-small-3-1-24b-instruct-2503| `mistralai/mistral-small-3-1-24b-instruct-2503`| ✅| ✅| |
mistral-large| `mistralai/mistral-large`| ✅| ✅| ✅|
mistral-medium-2505| `mistralai/mistral-medium-2505`| ✅| ✅| ✅|
mistral-small-24b-instruct-2501 (Deprecated)| `mistralai/mistral-small-24b-instruct-2501`| ✅| ✅| |
mixtral-8x7b-instruct-v01 (Deprecated)| `mistralai/mixtral-8x7b-instruct-v01`| ✅| ✅| ✅|
pixtral-12b| `mistralai/pixtral-12b`| ✅| ✅| ✅|
elyza-japanese-llama-2-7b-instruct| `elyza/elyza-japanese-llama-2-7b-instruct`| ✅| ✅| |
jais-13b-chat| `core42/jais-13b-chat`| ✅| ✅| |
allam-1-13b-instruct| `sdaia/allam-1-13b-instruct`| ✅| ✅| |
```

--------------------------------

### AutoAI RAG Experiment Status

Source: https://www.ibm.com/watsonx/developer/capabilities/autoai-rag

The `run()` method returns the status of the experiment. The status will be either `running` or `completed`.

```text
completed
```

--------------------------------

### Configure custom content filters in Python

Source: https://www.ibm.com/watsonx/developer/capabilities/text-generation

Define specific parameters for HAP (Hate, Abuse, Profanity) and PII (Personally Identifiable Information) filtering during generation.

```python
guardrails_hap_params = {
  GenTextModerationsMetaNames.INPUT: False,
  GenTextModerationsMetaNames.THRESHOLD: 0.45
}
guardrails_pii_params = {
  GenTextModerationsMetaNames.INPUT: False,
  GenTextModerationsMetaNames.OUTPUT: True,
  GenTextModerationsMetaNames.MASK: {"remove_entity_value": True}
}

response = model.generate(prompt,
  guardrails=True,
  guardrails_hap_params=guardrails_hap_params,
  guardrails_pii_params=guardrails_pii_params)
```

--------------------------------

### MS Marco Model Information

Source: https://www.ibm.com/watsonx/developer/get-started/models

Details regarding the ms-marco-MiniLM-L-12-v2 model configuration and pricing.

```APIDOC
## MS Marco Model Details

### Description
Provides configuration and pricing information for the MS Marco cross-encoder model.

### Model Information
- **Model Name**: ms-marco-MiniLM-L-12-v2
- **Model ID**: `cross-encoder/ms-marco-MiniLM-L-12-v2`
- **Max Documents**: 50
- **Price**: $0.000005 per 1K tokens
```

--------------------------------

### Visualize Time Series Data

Source: https://www.ibm.com/watsonx/developer/capabilities/time-series

Plot the actual total load using matplotlib.

```python
1import matplotlib.pyplot as plt
2import numpy as np
3
4plt.figure(figsize=(10,2))
5plt.plot(np.asarray(data[timestamp_column], 'datetime64[s]'), data[target_column])
6plt.title("Actual Total Load")
7plt.show()
```

--------------------------------

### Infer Text with watsonx.ai API

Source: https://www.ibm.com/watsonx/developer/get-started/quick-start

Make a POST request to the watsonx.ai text generation endpoint. Ensure you replace `{token}`, `{watsonx_ai_url}`, and `{project_id}` with your specific account details.

```curl
curl -X POST \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
"{watsonx_ai_url}/ml/v1/text/generation?version=2024-05-31" \
--data-raw '{
   "input": "How far is Paris from Bangalore?",
   "model_id": "ibm/granite-13b-instruct-v2",
   "project_id": "{project_id}"}'
```

--------------------------------

### IBM Granite Models

Source: https://www.ibm.com/watsonx/developer/get-started/models

Details on IBM's proprietary Granite foundation models, including their capabilities and pricing.

```APIDOC
## IBM Granite Models

### Supported API Functionality

Model| Model ID| Text Generation| Chat Completion| Tool Calling| Vision  
---|---|---|---|---|---
granite-3-3-8b-instruct| `ibm/granite-3-3-8b-instruct`| ✅| ✅| ✅|
granite-13b-instruct-v2| `ibm/granite-13b-instruct-v2`| ✅| ✅| ✅|
granite-8b-japanese (Deprecated)| `ibm/granite-8b-japanese`| ✅| | |
granite-3-8b-base| `ibm/granite-3-8b-base`| ✅| | |
granite-3-2b-instruct| `ibm/granite-3-2b-instruct`| ✅| ✅| ✅|
granite-3-8b-instruct| `ibm/granite-3-8b-instruct`| ✅| ✅| ✅|
granite-3-2-8b-instruct| `ibm/granite-3-2-8b-instruct`| ✅| ✅| ✅|
granite-guardian-3-2b| `ibm/granite-guardian-3-2b`| ✅| ✅| ✅|
granite-guardian-3-8b| `ibm/granite-guardian-3-8b`| ✅| ✅| ✅|
granite-3b-code-instruct (Deprecated)| `ibm/granite-3b-code-instruct`| ✅| | |
granite-8b-code-instruct| `ibm/granite-8b-code-instruct`| ✅| | |
granite-20b-code-instruct (Deprecated)| `ibm/granite-20b-code-instruct`| ✅| | |
granite-34b-code-instruct (Deprecated)| `ibm/granite-34b-code-instruct`| ✅| | |
granite-vision-3-2-2b| `ibm/granite-vision-3-2-2b`| | | | ✅

### Pricing and Max Tokens

Model Name| Model ID| Max Tokens (input + output)| Input Price (USD/1,000 tokens)| Output Price (USD/1,000 tokens)  
---|---|---|---|---
granite-3-3-8b-instruct| `ibm/granite-3-3-8b-instruct`| 131,072| $0.0002| $0.0002  
granite-13b-instruct-v2| `ibm/granite-13b-instruct-v2`| 8,192| $0.0006| $0.0006  
granite-8b-japanese| `ibm/granite-8b-japanese`| 4,096| $0.0006| $0.0006  
granite-3-8b-base| `ibm/granite-3-8b-base`| 4,096| $0.0006| $0.0006  
granite-3-2b-instruct| `ibm/granite-3-2b-instruct`| 131,072| $0.0001| $0.0001  
granite-3-8b-instruct| `ibm/granite-3-8b-instruct`| 131,072| $0.0002| $0.0002  
granite-3-2-8b-instruct| `ibm/granite-3-2-8b-instruct`| 131,072| $0.0002| $0.0002  
granite-guardian-3-2b| `ibm/granite-guardian-3-2b`| 131,072| $0.0001| $0.0001  
granite-guardian-3-8b| `ibm/granite-guardian-3-8b`| 131,072| $0.0002| $0.0002  
granite-3b-code-instruct| `ibm/granite-3b-code-instruct`| 128,000| $0.0006| $0.0006  
granite-8b-code-instruct| `ibm/granite-8b-code-instruct`| 128,000| $0.0006| $0.0006  
granite-20b-code-instruct| `ibm/granite-20b-code-instruct`| 8,192| $0.0006| $0.0006  
granite-34b-code-instruct| `ibm/granite-34b-code-instruct`| 8,192| $0.0006| $0.0006  
granite-vision-3-2-2b| `ibm/granite-vision-3-2-2b`| 131,072| $0.0001| $0.0001  
```

--------------------------------

### Make a text generation API request using cURL

Source: https://www.ibm.com/watsonx/developer

Use this cURL command to send a POST request to the watsonx.ai text generation endpoint. Ensure you replace placeholders for token, watsonx_ai_url, and project_id.

```curl
curl -X POST \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
"{watsonx_ai_url}/ml/v1/text/generation?version=2024-05-31" \
--data-raw '{
   "input": "How far is Paris from Bangalore?",
   "model_id": "ibm/granite-13b-instruct-v2",
   "project_id": "{project_id}" 
}'
```

--------------------------------

### Stream text generation in Node.js

Source: https://www.ibm.com/watsonx/developer/capabilities/text-generation

Enable streaming for text generation tasks using the Node.js SDK.

```javascript
try {
  const textGenerationStream = watsonxAIService
    .generateTextStream(params)
    .then(async (res) => {
      console.log(res);

      for await (const line of res) {
        console.log(line);
      }
    });
} catch (err) {
  console.warn(err);
}
```

--------------------------------

### Submit a text extraction request

Source: https://www.ibm.com/watsonx/developer/capabilities/text-extraction

Submits a POST request to the extraction service for a specified PDF file.

```bash
curl --request POST 'https://{cluster_url}/ml/v1/text/extractions?version=2023-10-25'
-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'
-H 'Content-Type: application/json'
-H 'Accept: application/json'
-d '{
  "project_id": "12ac4cf1-252f-424b-b52d-5cdd9814987f"
  "document_reference": {
    "type": "connection_asset",
    "connection": {
      "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d"
    },
    "location": {
      "file_name": "files/document.pdf"
    }
  },
  "results_reference": {
    "type": "connection_asset",
    "connection": {
      "id": "6f5688fd-f3bf-42c2-a18b-49c0d8a1920d"
    },
    "location": {
      "file_name": "results"
    }
  },
  "steps": {
    "tables_processing": {
      "enabled": true
    }
  }
}'
```

--------------------------------

### Define TSForecastParameters

Source: https://www.ibm.com/watsonx/developer/capabilities/time-series

Define the parameters for time series forecasting, including the timestamp column, forecast frequency, and target columns.

```python
from ibm_watsonx_ai.foundation_models.schema import TSForecastParameters

forecasting_params = TSForecastParameters(
    timestamp_column=timestamp_column,
    freq="1h",
    target_columns=[target_column],
)
```

--------------------------------

### Process extracted text with jq

Source: https://www.ibm.com/watsonx/developer/capabilities/text-extraction

Commands to extract text tokens or page counts from the generated JSON report.

```bash
cat output_report | jq '[.all_structures.tokens[].text] | join(" ")' > parsed_output_text.txt
```

```bash
cat output_report.json | jq '.metadata.num_pages'
```

--------------------------------

### Create IAM Bearer Token

Source: https://www.ibm.com/watsonx/developer/get-started/quick-start

Use this curl command to generate a bearer token from your API key. Replace `{apikey}` with your actual IBM Cloud API key.

```curl
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
https://iam.cloud.ibm.com/identity/token \
-d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey={apikey}"
```

--------------------------------

### Create an IAM access token

Source: https://www.ibm.com/watsonx/developer/capabilities/text-rerank

Generate an access token required for API authentication by providing your API key to the IAM Identity Services.

```curl
curl -X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey={api_key}' \
'https://iam.cloud.ibm.com/identity/token'
```

--------------------------------

### Send request to re-rank endpoint

Source: https://www.ibm.com/watsonx/developer/capabilities/text-rerank

Submit a query and a list of input texts to the re-rank endpoint to receive relevance scores.

```curl
curl --request POST \
"https://{cluster_url}/ml/v1/text/rerank?version=2023-10-25" \
-H 'Authorization: Bearer {access_token}' \
-H 'Accept: application/json' \
-d '{
  "model_id": "cross-encoder/ms-marco-minilm-l-12-v2",
  "project_id": "{project_id}",
  "inputs": [
    {
      "text": "In my younger years, I often reveled in the excitement of spontaneous adventures and embraced the thrill of the unknown, whereas in my grownup life, I've come to appreciate the comforting stability of a well-established routine."
    },
    {
      "text": "As a young man, I frequently sought out exhilarating experiences, craving the adrenaline rush of life's novelties, while as a responsible adult, I've come to understand the profound value of accumulated wisdom and life experience."
    }
  ],
  "query": "As a Youth, I craved excitement while in adulthood I followed Enthusiastic Pursuit.",
  "parameters": {
    "return_options": {
      "top_n": 2 // Number of top results to return
    }
  }
}'
```

--------------------------------

### Generate text embeddings using cURL

Source: https://www.ibm.com/watsonx/developer/capabilities/embeddings

Use this cURL command to send text inputs to the embeddings API. Replace the placeholder token, URL, and project ID with your specific credentials.

```bash
curl -X POST \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{
  \"inputs\": [
    \"Youth craves thrills while adulthood cherishes wisdom.\",
    \"Youth seeks ambition while adulthood finds contentment.\",
    \"Dreams chased in youth while goals pursued in adulthood.\"
  ],
  \"model_id\": \"ibm/slate-125m-english-rtrvr\",
  \"project_id\": \"12ac4cf1-252f-424b-b52d-5cdd9814987f\"
}" \
"{watsonx_ai_url}/ml/v1/text/embeddings?version=2024-05-31"
```

--------------------------------

### Split Time Series Data

Source: https://www.ibm.com/watsonx/developer/capabilities/time-series

Partition the dataset into historical context and future prediction segments.

```python
1timestamp_column = "time"
2target_column = "total load actual"
3context_length = 608
4future_context = 96
5
6# Only use the last `context_length` rows for prediction.
7future_data = df.iloc[-future_context:,]
8data = df.iloc[-context_length:-future_context,]
```

--------------------------------

### Perform Forecasting

Source: https://www.ibm.com/watsonx/developer/capabilities/time-series

Call the forecast() method on the TSModelInference instance to predict future values based on the provided data and parameters.

```python
results = ts_model.forecast(data=data, params=forecasting_params)['results'][0]
```

--------------------------------

### POST /ml/v1/text/rerank

Source: https://www.ibm.com/watsonx/developer/capabilities/text-rerank

This endpoint performs re-ranking on a set of input texts against a query using a specified cross-encoder model.

```APIDOC
## POST /ml/v1/text/rerank

### Description
Re-ranks a list of input documents based on their relevance to a provided query using a cross-encoder model.

### Method
POST

### Endpoint
https://{cluster_url}/ml/v1/text/rerank?version=2023-10-25

### Parameters
#### Query Parameters
- **version** (string) - Required - The API version date.

#### Request Body
- **model_id** (string) - Required - The ID of the cross-encoder model to use.
- **project_id** (string) - Required - The ID of the project.
- **inputs** (array) - Required - A list of objects containing the text to be ranked.
- **query** (string) - Required - The query string to rank against.
- **parameters** (object) - Optional - Configuration parameters for the request.

### Request Example
{
  "model_id": "cross-encoder/ms-marco-minilm-l-12-v2",
  "project_id": "{project_id}",
  "inputs": [
    { "text": "In my younger years..." },
    { "text": "As a young man..." }
  ],
  "query": "As a Youth, I craved excitement...",
  "parameters": {
    "return_options": {
      "top_n": 2
    }
  }
}

### Response
#### Success Response (200)
- **model_id** (string) - The model used.
- **results** (array) - List of ranked results with index and score.
- **created_at** (string) - Timestamp of the request.
- **input_token_count** (integer) - Number of tokens processed.

#### Response Example
{
  "model_id": "cross-encoder/ms-marco-minilm-l-12-v2",
  "results": [
    { "index": 1, "score": 0.7461 },
    { "index": 0, "score": 0.8274 }
  ],
  "created_at": "2024-02-21T17:32:28Z",
  "input_token_count": 20
}
```

--------------------------------

### Message history with tool result

Source: https://www.ibm.com/watsonx/developer/capabilities/tool-calling

The structure of the message history when passing the tool result back to the model for the final answer.

```json
[
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "What is 2 plus 4?"
      }
    ]
  },
  {
    "role": "assistant",
    "tool_calls": [
      {
        "id": "chatcmpl-tool-77cbe4e94d88489383a0c6ed1b644674",
        "type": "function",
        "function": {
          "name": "add",
          "arguments": "{\"a\": 2, \"b\": 4}"
        }
      }
    ]
  },
  {
    "role": "tool",
    "tool_call_id": "chatcmpl-tool-77cbe4e94d88489383a0c6ed1b644674",
    "content": [
      {
        "type": "text",
        "text": "6"
      }
    ]
  }
]
```

--------------------------------

### Plot Historical and Predicted Data

Source: https://www.ibm.com/watsonx/developer/capabilities/time-series

Visualize the historical data, predicted values, and true future values using matplotlib for comparison.

```python
import matplotlib.pyplot as plt
import numpy as np

plt.figure(figsize=(10,2))
plt.plot(np.asarray(data[timestamp_column], dtype='datetime64[s]'), data[target_column], label="Historical data")
plt.plot(np.asarray(results[timestamp_column], dtype='datetime64[s]'), results[target_column], label="Predicted")
plt.plot(np.asarray(future_data[timestamp_column], dtype='datetime64[s]'), future_data[target_column], label="True", linestyle='dashed')
plt.legend(loc='center left', bbox_to_anchor=(1, 0.5))
plt.show()
```

--------------------------------

### Define Time Series Model

Source: https://www.ibm.com/watsonx/developer/capabilities/time-series

Specify the model ID for inference.

```python
1ts_model_id = client.foundation_models.TimeSeriesModels.GRANITE_TTM_512_96_R2
```

--------------------------------

### Re-rank API response structure

Source: https://www.ibm.com/watsonx/developer/capabilities/text-rerank

The JSON response contains the model ID, a list of results with indices and scores, and metadata.

```json
{
  "model_id": "cross-encoder/ms-marco-minilm-l-12-v2",
  "results": [
    {
      "index": 1,
      "score": 0.7461
    },
    {
      "index": 0,
      "score": 0.8274
    }
  ],
  "created_at": "2024-02-21T17:32:28Z",
  "input_token_count": 20
}
```

--------------------------------

### Embeddings API response format

Source: https://www.ibm.com/watsonx/developer/capabilities/embeddings

The API returns a JSON object containing the model ID, the generated embeddings for each input, and metadata such as the creation timestamp and token count.

```json
{
  \"model_id\": \"ibm/slate-125m-english-rtrvr\",
  \"results\": [
    {
      \"embedding\": [-0.006929283, -0.005336422, -0.024047505]
    }
  ],
  \"created_at\": \"2024-02-21T17:32:28Z\",
  \"input_token_count\": 10
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.