### Run Solace AI Connector with OpenAI Example

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/getting_started.md

This command initiates the Solace AI Connector using the downloaded OpenAI example configuration file. Ensure all prerequisite environment variables and Python dependencies are installed before execution.

```sh
solace-ai-connector langchain_openai_with_history_chat.yaml
```

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

### Setup and Install Solace AI Connector

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/tips_and_tricks.md

These bash commands set up a new directory, create a virtual environment, install the solace-ai-connector package, and create necessary files for the example. This prepares the environment for custom module development.

```bash
mkdir -p module-example/src
cd module-example
python3 -m venv env
source env/bin/activate
pip install solace-ai-connector
touch config.yaml src/custom_component.py src/custom_function.py src/__init__.py
```

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

### Download OpenAI Connector Example Configuration

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/getting_started.md

This command downloads the example configuration file for an OpenAI connector using Langchain. It utilizes `curl` to fetch the YAML file from a GitHub repository. Ensure you have `curl` installed on your system.

```sh
curl https://raw.githubusercontent.com/SolaceLabs/solace-ai-connector/refs/heads/main/examples/llm/langchain_openai_with_history_chat.yaml > langchain_openai_with_history_chat.yaml
```

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

### YAML Logging Configuration Example

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/logging.md

An example YAML configuration for logging, demonstrating formatters, handlers for console and rotating files, and specific logger configurations for 'solace_ai_connector' and 'sam_trace'. It also shows root logger setup and environment variable substitution.

```yaml
version: 1
disable_existing_loggers: false

formatters:
  simpleFormatter:
    format: "% (asctime)s | % (levelname) - 5s | % (threadName)s | % (name)s | % (message)s"

handlers:
  streamHandler:
    class: logging.StreamHandler
    formatter: simpleFormatter
    stream: "ext://sys.stdout"

  rotatingFileHandler:
    class: logging.handlers.RotatingFileHandler
    formatter: simpleFormatter
    filename: "${LOGGING_FILE_NAME, app.log}"
    mode: a
    maxBytes: 52428800  # 50MB
    backupCount: 10

loggers:
  solace_ai_connector:
    level: INFO  
    handlers: []
    qualname: solace_ai_connector
    propagate: true

  sam_trace:
    level: INFO
    handlers: []
    qualname: sam_trace
    propagate: true

root:
  level: "${LOGGING_ROOT_LEVEL, WARNING}"
  handlers: [streamHandler, rotatingFileHandler]
```

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

### Synchronous Request-Response Example (Python)

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/guides/broker_request_response.md

Demonstrates sending a request message and blocking until a single response is received or a timeout occurs. This pattern is suitable for immediate feedback scenarios. The response is processed upon receipt.

```python
# In your component's invoke method
from solace_ai_connector.common.message import Message

request_message = Message(payload={"query": "user_profile", "id": 123}, topic="service/request")

try:
    # This call will block until a response is received or it times out
    response_message = self.do_broker_request_response(request_message)
    if response_message:
        log.info(f"Received response: {response_message.get_payload()}")
        return response_message.get_payload()
except TimeoutError:
    log.error("Request for user profile timed out.")
    return {"error": "timeout"}
```

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

### Install Project Requirements

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/getting_started.md

This command installs all the necessary Python packages listed in the `requirements.txt` file. It's crucial for ensuring the connector has all its dependencies met.

```sh
pip install -r requirements.txt
```

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

### Install and Run Solace AI Connector (Bash)

Source: https://context7.com/solacelabs/solace-ai-connector/llms.txt

Provides commands for installing the Solace AI Connector from PyPI, including options for specific features. It also shows how to set necessary environment variables for broker connection and run the connector using configuration files, including merging multiple files and loading environment variables from a file.

```bash
# Install from PyPI
pip install solace-ai-connector

# Install with specific features
pip install solace-ai-connector[openai,langchain,chromadb-vector-store]

# Set environment variables
export SOLACE_BROKER_URL=ws://localhost:8008
export SOLACE_BROKER_USERNAME=default
export SOLACE_BROKER_PASSWORD=default
export SOLACE_BROKER_VPN=default

# Run with configuration file
solace-ai-connector config.yaml

# Run with multiple config files (merged)
solace-ai-connector base-config.yaml app-config.yaml

# Load environment variables from file
solace-ai-connector --envfile .env config.yaml
```

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

### Install Langchain OpenAI Dependencies

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/getting_started.md

This command installs the necessary Python libraries for integrating Langchain with OpenAI. It uses `pip`, the Python package installer, to download and set up `langchain_openai` and `openai`.

```sh
pip install langchain_openai openai
```

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

### FilterTransform Configuration Example

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/transforms/filter.md

This example demonstrates the configuration of the FilterTransform, specifying the source list, the filtering logic using an invoke function, and the destination for the filtered items. It highlights how to access current item values within the filter function.

```yaml
input_transforms:
  - type: filter
    source_list_expression: input.payload:my_obj.my_list
    source_expression: item
    filter_function:
      invoke:
        module: invoke_functions
        function: greater_than
          params:
            positional:
              - evaluate_expression(keyword_args:current_value.my_val)
              - 2
    dest_expression: user_data.output:new_list
```

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

### Reduce Transform Example Configuration

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/transforms/reduce.md

An example illustrating the configuration of a reduce transform to sum values from a list. It specifies the source list, the value to accumulate, an add function for accumulation, and the destination for the result.

```yaml
input_transforms:
  - type: reduce
    source_list_expression: input.payload:my_obj.my_list
    source_expression: item.my_val
    initial_value: 0
    accumulator_function:
      invoke:
        module: invoke_functions
        function: add
          params:
            positional:
              - evaluate_expression(keyword_args:accumulated_value)
              - evaluate_expression(keyword_args:current_value)
    dest_expression: user_data.output:my_obj.sum
```

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

### Example Flow Definition in YAML

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/llms.txt

Shows how to define a single processing pipeline (Flow) within a Standard App configuration using YAML. It specifies a sequence of components, including their names, modules, and configuration settings.

```yaml
flows:
  - name: data_processing_flow
    components:
      - component_name: input_reader
        component_module: broker_input
        component_config: { ... }
      - component_name: processor
        component_module: my_custom_processor
        component_config: { ... }
      - component_name: output_writer
        component_module: broker_output
        component_config: { ... }
```

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

### Async Context Request-Response Handling (Python)

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/guides/broker_request_response.md

This Python example demonstrates how to perform non-blocking request-response operations within an asyncio context using the 'do_broker_request_response_async' method. It emphasizes the use of 'await' to prevent blocking the event loop and shows how to run asynchronous logic from a synchronous 'invoke' method using 'asyncio.run'.

```python
# In your component's code
import asyncio
from solace_ai_connector.common.message import Message

async def my_async_logic(self, data):
    request_msg = Message(payload=data, topic="service/request")

    # Correctly await the async version of the method
    response_msg = await self.do_broker_request_response_async(request_msg)

    if response_msg:
        return response_msg.get_payload()
    return None

def invoke(self, message, data):
    # You can run your async logic from the synchronous invoke method
    return asyncio.run(self.my_async_logic(data))
```

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

### WebSocket Example App UI Styles (CSS)

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/examples/websocket/websocket_example_app.html

This CSS code defines the visual appearance and layout for the WebSocket Example App. It includes styling for various UI components such as containers, headers, inputs, buttons, and messages, with support for dark mode.

```css
:root { --bg-color: #e6f3ff; --container-bg: #ffffff; --text-color: #333333; --header-color: #3498db; --input-bg: #f8f9fa; --input-border: #ced4da; --button-bg: #3498db; --button-color: #ffffff; --button-hover: #2980b9; --message-bg: #ffffff; --message-border: #e9ecef; --message-alt-bg: #f8f9fa; --timestamp-color: #6c757d; --error-color: #dc3545; --shadow-color: rgba(0, 0, 0, 0.1); } @media (prefers-color-scheme: dark) { :root { --bg-color: #1a1a1a; --container-bg: #2c2c2c; --text-color: #e0e0e0; --header-color: #4fa3d1; --input-bg: #3a3a3a; --input-border: #555555; --button-bg: #4fa3d1; --button-color: #ffffff; --button-hover: #3a7ca5; --message-bg: #2c2c2c; --message-border: #444444; --message-alt-bg: #333333; --timestamp-color: #a0a0a0; --error-color: #ff6b6b; --shadow-color: rgba(0, 0, 0, 0.3); } } body { font-family: 'Roboto', Arial, sans-serif; background-color: var(--bg-color); color: var(--text-color); line-height: 1.6; padding: 20px; transition: background-color 0.3s, color 0.3s; } .container { max-width: 800px; margin: 0 auto; background-color: var(--container-bg); padding: 20px 30px; border-radius: 8px; box-shadow: 0 2px 10px var(--shadow-color); transition: background-color 0.3s, box-shadow 0.3s; } h1, h2 { margin-top: 0; color: var(--header-color); margin-bottom: 20px; transition: color 0.3s; } #connection-section, #input-section, #output-section { background-color: var(--input-bg); padding: 20px; margin-bottom: 30px; border-radius: 8px; box-shadow: 0 1px 3px var(--shadow-color); transition: background-color 0.3s, box-shadow 0.3s; } input[type="text"], #json-input { width: calc(100% - 20px); /* Subtract 20px to account for padding */ padding: 10px; border: 1px solid var(--input-border); border-radius: 4px; font-size: 16px; background-color: var(--input-bg); color: var(--text-color); transition: background-color 0.3s, color 0.3s, border-color 0.3s; margin-bottom: 10px; /* Add space below inputs */ } button { margin-top: 5px; /* Add space above buttons */ background-color: var(--button-bg); color: var(--button-color); border: none; padding: 10px 20px; border-radius: 4px; cursor: pointer; transition: background-color 0.3s, color 0.3s; } button:hover { background-color: var(--button-hover); } #status { font-weight: bold; margin-left: 10px; color: var(--header-color); transition: color 0.3s; } .message { background-color: var(--message-bg); border: 1px solid var(--message-border); border-radius: 4px; padding: 15px; margin-bottom: 15px; transition: background-color 0.3s, border-color 0.3s; } .message:nth-child(even) { background-color: var(--message-alt-bg); } .timestamp { font-size: 0.8em; color: var(--timestamp-color); transition: color 0.3s; } .error { color: var(--error-color); margin-top: 5px; transition: color 0.3s; } @media (max-width: 600px) { body { padding: 10px; } .container { padding: 15px; } input[type="text"], #json-input, button { font-size: 14px; } }
```

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

### Example Aggregate Component Configuration - YAML

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/components/aggregate.md

An example illustrating how to configure the Aggregate component. This example sets a maximum of 3 items to aggregate and a timeout of 1000 milliseconds, while specifying that the 'text' field from the input payload should be used as the source for aggregation.

```yaml
   - component_name: aggretator_example
     component_module: aggregate
     component_config: 
       # The maximum number of items to aggregate before sending the data to the next component
       max_items: 3
        # The maximum time to wait before sending the data to the next component
       max_time_ms: 1000
     input_selection:
       # Take the text field from the message and use it as the input to the aggregator
       source_expression: input.payload:text
```

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

### Streaming Response Example (Python)

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/guides/broker_request_response.md

Illustrates sending a request and receiving multiple response chunks over time, aggregating them into a single result. The stream termination is determined by a specific condition in the payload, such as `{"done": true}`.

```python
# In your component's invoke method
request_message = Message(payload={"prompt": "Tell me a long story"}, topic="llm/request/stream")

# This expression will be evaluated on each response chunk.
# The stream ends when a chunk's payload contains `{"done": true}`.
streaming_complete_expr = "input.payload:done"

try:
    response_generator = self.do_broker_request_response(
        request_message,
        stream=True,
        streaming_complete_expression=streaming_complete_expr
    )

    full_story = ""
    for chunk_message, is_last in response_generator:
        chunk_payload = chunk_message.get_payload()
        full_story += chunk_payload.get("text", "")
        if is_last:
            log.info("Final chunk received. Story is complete.")
            break

    return {"story": full_story}
except TimeoutError:
    log.error("Streaming request timed out.")
    return {"error": "timeout"}
```

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

### Install Boto3 for AWS Bedrock Interaction

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/components/litellm_chat_model.md

To enable the Solace AI Connector to interact with AWS Bedrock, the 'boto3' library, the AWS SDK for Python, must be installed. This command ensures the necessary dependencies are available in your Python environment.

```bash
pip install boto3
```

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

### Example App Definitions in YAML

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/llms.txt

Illustrates the structure for defining both Standard and Simplified Apps within the Solace AI Connector configuration using YAML. Standard Apps explicitly define flows, while Simplified Apps define broker interactions and components directly.

```yaml
apps:
  # Standard App
  - name: my_standard_app
    app_config: { global_param: "value" }
    flows:
      - name: my_flow
        components: [ ... ] # Component definitions here
  # Simplified App
  - name: my_simplified_app
    broker: { ... } # Broker connection and interaction settings
    app_config: { api_key: ${API_KEY} }
    components: [ ... ] # Component definitions here
```

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

### Configuring AWS Bedrock with LiteLLMChatModel

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/components/litellm_chat_model.md

This example demonstrates how to configure the `load_balancer` parameter within `LiteLLMChatModel` to utilize AWS Bedrock. It shows the structure for specifying Bedrock models and their associated parameters, including API keys and region.

```yaml
component_config:
  load_balancer:
    - model_name: 'my-bedrock-claude-model'
      litellm_params:
        model: 'bedrock/anthropic.claude-3-sonnet-20240229-v1:0'
        aws_access_key_id: 'YOUR_ACCESS_KEY'
        aws_secret_access_key: 'YOUR_SECRET_KEY'
        aws_region_name: 'us-east-1'
        temperature: 0.5
        max_tokens: 1024
```

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

### Include Multiple Configuration Files

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/configuration.md

Demonstrates how to start the Solace AI Connector with multiple YAML configuration files. The files are merged, with later files overriding earlier ones for duplicate keys, and arrays are concatenated. This allows for modular configuration management.

```bash
python3 -m solace_ai_connector.main config1.yaml config2.yaml
```

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

### Dynamic Configuration with Invoke Keyword (YAML)

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/configuration.md

This example demonstrates the use of the `invoke` keyword in YAML configuration to dynamically fetch values, such as AWS credentials. It shows how to specify a module, object, function, or attribute, along with parameters for function calls.

```yaml
credentials:
  access_key_id:
    invoke:
      module: os.environ
      attribute: get
      params:
        positional: ["AWS_ACCESS_KEY_ID"]
  secret_access_key:
    invoke:
      module: os.environ
      attribute: get
      params:
        positional: ["AWS_SECRET_ACCESS_KEY"]
```

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

### Run Solace AI Connector with Configuration

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/tips_and_tricks.md

This bash command executes the Solace AI Connector using the specified configuration file. This command starts the flow defined in 'config.yaml', processing data through custom components and transforms.

```bash
solace-ai-connector config.yaml
```

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

### Publish Event to OpenAI Connector

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/getting_started.md

This demonstrates publishing a sample JSON event to the `demo/joke/subject` topic, intended for the OpenAI connector example. The payload contains a 'joke' object with a 'subject' field. Remember to also subscribe to `demo/joke/subject/response` to view the connector's reply.

```json
{
  "joke": {
    "subject": "<subject for the joke>"
  }
}
```

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

### Invoke Custom Python Functions

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/configuration.md

This example illustrates how to invoke custom Python functions defined in a specified module. It uses the 'invoke' configuration with 'path', 'module', and 'function' to point to the custom logic, allowing for parameterized function calls.

```yaml
# Inside component_config or another value field
some_dynamic_value:
  invoke:
    path: .
    module: src.my_module
    function: my_function
    params:
      positional:
        - 1
        - 2
```

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

### Run Solace AI Connector with SimpleEchoApp in Python

Source: https://context7.com/solacelabs/solace-ai-connector/llms.txt

Demonstrates how to initialize and run the SolaceAiConnector with the SimpleEchoApp defined in the current module. It includes basic connector configuration for logging and app definitions, and handles graceful shutdown.

```python
if __name__ == "__main__":
    from solace_ai_connector.solace_ai_connector import SolaceAiConnector

    connector_config = {
        "log": {
            "stdout_log_level": "INFO",
            "log_file_level": "DEBUG",
            "log_file": "connector.log"
        },
        "apps": [
            {
                "name": "echo_instance",
                "app_module": __name__  # Points to this module
            }
        ]
    }

    connector = SolaceAiConnector(config=connector_config)
    connector.run()

    try:
        while True:
            time.sleep(5)
    except KeyboardInterrupt:
        connector.stop()
        connector.cleanup()
```

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

### Defining App Configuration in Python

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/simplified-apps.md

Illustrates how to define an application's structure, including components and configuration, directly within a Python file. This is an alternative to defining components solely in YAML.

```python
from solace_ai_connector.flow.app import App
from solace_ai_connector.flow.component import ComponentBase

class MyComponent(ComponentBase):
    # ... component logic ...
    pass

class MyApp(App):
    app_config = App.Config(
        component_class=MyComponent, # References the defined component class
        # Other app-level configurations can go here
        code_defined_param="default_value"
    )

# This file (e.g., my_app_definition.py) would then be referenced in YAML:
# apps:
#   - name: my_code_app_instance
#     app_module: my_app_definition
#     config:
#       code_defined_param: "override_from_yaml"
```

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

### MapTransform Output Payload Example

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/transforms/map.md

Example of the output payload structure produced by the MapTransform configuration.

```json
{
    "new_list": [3, 4, 5]
}
```

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

### MapTransform Input Payload Example

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/transforms/map.md

Example of the input payload structure expected by the MapTransform configuration.

```json
{
  "my_obj": {
    "my_list": [
      {"my_val": 1},
      {"my_val": 2},
      {"my_val": 3}
    ]
  }
}
```

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

### Simplified App Configuration in YAML

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/llms.txt

Outlines the configuration for a simplified application, which includes broker connection details, optional instance scaling, app configuration, and a list of components with their subscriptions and transformations.

```yaml
apps:
  - name: my_simplified_app
    num_instances: 1 # Optional: Scales the whole app definition
    broker:
      # Connection details (url, vpn, user, pass) - REQUIRED
      input_enabled: true # REQUIRED to receive
      output_enabled: false # Optional
      request_reply_enabled: false # Optional
      queue_name: "q/my_app/in" # REQUIRED if input_enabled
      # Other optional broker settings (encoding, format, create_queue, etc.)
    app_config: # Optional: App-level config
      api_key: ${API_KEY}
    components:
      - name: processor1
        component_module: my_module # OR component_class: MyClass
        component_config: {...}
        subscriptions: # REQUIRED if input_enabled
          - topic: "data/input/>"
        num_instances: 1 # Optional: Scales only this component
        input_transforms: [...] # Optional
        input_selection: {...} # Optional
      # - name: processor2 ...
```

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

### Implement Custom Component Initialization (Python)

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/llms.txt

This Python snippet demonstrates the implementation of the '__init__' method for a custom Solace AI Connector component. It shows how to inherit from 'ComponentBase', call the superclass constructor with the 'info' dictionary, and access configuration parameters using 'self.get_config()'.

```Python
from solace_ai_connector.components.component_base import ComponentBase
from .my_custom_component_info import info # Assuming info is in a separate file

class MyCustomComponent(ComponentBase):
    def __init__(self, **kwargs):
        # MUST call super().__init__ with the info dict
        super().__init__(info, **kwargs)
        # Access config using self.get_config() AFTER super().__init__
        self.param1 = self.get_config("param1")
        self.param2 = self.get_config("param2")
        # Other initialization like setting up clients, etc.
        log.info("%s Initialized with param1=%s, param2=%d",
                 self.log_identifier, self.param1, self.param2)
```

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

### MapTransform Example Configuration

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/transforms/map.md

An example demonstrating how to configure the MapTransform to iterate over a list, apply a processing function, and map the results to a new list.

```yaml
input_transforms:
  - type: map
    source_list_expression: input.payload:my_obj.my_list
    source_expression: item.my_val
    processing_function:
      invoke:
        module: invoke_functions
        function: add
          params:
            positional:
              - evaluate_expression(keyword_args:current_value)
              - 2
    dest_list_expression: user_data.output:new_list
```

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

### Run Solace AI Connector with Simplified App

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/getting_started.md

This command executes the Solace AI Connector using a specified YAML configuration file for a simplified application. Ensure that the necessary Solace broker environment variables are correctly set before running.

```sh
solace-ai-connector simple_echo.yaml
```

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

### Create and Activate Python Virtual Environment

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/getting_started.md

This optional step creates an isolated Python environment using `venv` and activates it. Using a virtual environment is recommended to manage project dependencies separately.

```sh
python -m venv .venv
source .venv/bin/activate
```

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

### Run Solace AI Connector (Bash)

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/llms.txt

This bash command executes the Solace AI Connector using the 'simplified_suffix_app.yaml' configuration file. Ensure all necessary Solace environment variables (like SOLACE_BROKER_URL) are set before running. This command assumes the custom component source file is accessible.

```bash
# Set Solace env vars first
# export SOLACE_BROKER_URL=...
# export SOLACE_BROKER_VPN=...
# export SOLACE_BROKER_USERNAME=...
# export SOLACE_BROKER_PASSWORD=...
# Assuming src/custom_suffix.py exists relative to current directory
solace-ai-connector simplified_suffix_app.yaml

```

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

### Iterate Component Example Configuration

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/components/iterate.md

An example of how to configure the Iterate component, including selecting a specific list field from the input message payload as the source for iteration. The `input_selection.source_expression` points to the 'embeddings' field within the input payload.

```yaml
- component_name: iterate_example
  component_module: iterate
  component_config: 
  input_selection:
    # Take the list field from the message and use it as the input to the iterator
    source_expression: input.payload:embeddings

```

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

### Solace AI Connector: Copy Transform Example

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/llms.txt

An example of a 'copy' transform in Solace AI Connector, demonstrating how to copy a field from the input payload to user data. This transform is applied sequentially to modify the Message object before further processing.

```yaml
input_transforms:
  - type: copy
    source_expression: input.payload:user_id
    dest_expression: user_data.session:current_user_id
```

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

### Request-Response Operations

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/guides/broker_request_response.md

APIs for performing request-response operations, including synchronous, streaming, and asynchronous patterns.

```APIDOC
## POST /solacelabs/solace-ai-connector/request-response/sync

### Description
Performs a synchronous request-response operation. The component sends a request and waits for a single reply. This call will block until a response is received or it times out.

### Method
POST

### Endpoint
/solacelabs/solace-ai-connector/request-response/sync

### Parameters
#### Request Body
- **request_message** (object) - Required - The message to send for the request.
  - **payload** (any) - Required - The payload of the message.
  - **topic** (str) - Required - The topic to send the request to.

### Request Example
```json
{
  "request_message": {
    "payload": {"query": "user_profile", "id": 123},
    "topic": "service/request"
  }
}
```

### Response
#### Success Response (200)
- **response_message** (object) - The received response message.
  - **payload** (any) - The payload of the response message.

#### Error Response (Timeout)
- **error** (str) - "timeout"

#### Response Example
```json
{
  "response_message": {
    "payload": {"user_data": "..."}
  }
}
```

---

## POST /solacelabs/solace-ai-connector/request-response/stream

### Description
Performs a streaming request-response operation. The component receives multiple chunks of a response and aggregates them. The stream ends when a chunk's payload contains `{"done": true}`.

### Method
POST

### Endpoint
/solacelabs/solace-ai-connector/request-response/stream

### Parameters
#### Request Body
- **request_message** (object) - Required - The message to send for the request.
  - **payload** (any) - Required - The payload of the message.
  - **topic** (str) - Required - The topic to send the request to.
- **streaming_complete_expression** (str) - Required - An expression evaluated on each response chunk to determine if the stream is complete (e.g., `"input.payload:done"`).

### Request Example
```json
{
  "request_message": {
    "payload": {"prompt": "Tell me a long story"},
    "topic": "llm/request/stream"
  },
  "streaming_complete_expression": "input.payload:done"
}
```

### Response
#### Success Response (200)
- **story** (str) - The aggregated response from the streaming request.

#### Error Response (Timeout)
- **error** (str) - "timeout"

#### Response Example
```json
{
  "story": "Once upon a time..."
}
```

---

## POST /solacelabs/solace-ai-connector/request-response/async

### Description
Initiates an asynchronous request (fire-and-forget). The requesting component sets `wait_for_response=False` and continues processing immediately. A separate flow handles the reply.

### Method
POST

### Endpoint
/solacelabs/solace-ai-connector/request-response/async

### Parameters
#### Request Body
- **request_message** (object) - Required - The message to send for the request.
  - **payload** (any) - Required - The payload of the message.
  - **topic** (str) - Required - The topic to send the request to.
- **wait_for_response** (bool) - Required - Set to `False` to indicate an asynchronous request.

### Request Example
```json
{
  "request_message": {
    "payload": {"command": "start_process", "data": "..."},
    "topic": "process/control"
  },
  "wait_for_response": false
}
```

### Response
#### Success Response (200)
- **status** (str) - Indicates the request was successfully sent.

#### Response Example
```json
{
  "status": "request sent asynchronously"
}
```
```

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

### Request-Reply with Broker (Python)

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/simplified-apps.md

Shows how to send a request to the broker and receive a single response or a stream of responses using `do_broker_request_response`. It includes checks for enabling the feature and handling potential `None` responses.

```python
if self.is_broker_request_response_enabled():
    request_payload = {"query": "some data"}
    request_topic = "service/request/topic"
    request_message = Message(payload=request_payload, topic=request_topic)

    # For a single response:
    response_message = self.do_broker_request_response(request_message)
    if response_message:
        response_payload = response_message.get_payload()
        # ... process response ...

    # For streaming responses:
    # response_generator = self.do_broker_request_response(
    #     request_message,
    #     stream=True,
    #     streaming_complete_expression="input.payload:is_last_chunk" # Example expression
    # )
    # for response_message, is_last in response_generator:
    #     # ... process chunk ...
    #     if is_last:
    #         break
else:
    log.warning("Request-reply is not enabled for this app.")
```

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

### Dynamic Multi-Session Management (Python)

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/guides/broker_request_response.md

This Python code illustrates how a component can dynamically manage multiple request-response sessions, typically for different tenants. It includes logic to create a new session if one doesn't exist for a given tenant, configuring it with tenant-specific broker details and response topics. It then uses this session to send a request and handles potential errors by destroying the session.

```python
# In an advanced component with multi-session mode enabled
def invoke(self, message, data):
    tenant_id = data.get("tenant_id")
    tenant_broker_url = self.get_tenant_broker_url(tenant_id) # Your logic to get tenant config

    # Create a session for this tenant if it doesn't exist
    session_id = self.kv_store_get(f"session_{tenant_id}")
    if not session_id:
        log.info(f"Creating new session for tenant {tenant_id}")
        # Create a new session with tenant-specific configuration
        session_id = self.create_request_response_session(
            session_config={
                "broker_config": {
                    "broker_url": tenant_broker_url,
                    "broker_vpn": f"vpn-for-{tenant_id}"
                    # Other broker settings can be provided here
                },
                "request_expiry_ms": 60000, # Longer timeout for this tenant
                "response_topic_prefix": f"replies/tenant/{tenant_id}"
            }
        )
        self.kv_store_set(f"session_{tenant_id}", session_id)

    # Use the specific session for the request
    request_message = Message(payload=data.get("payload"), topic="tenant/service")
    try:
        response = self.do_broker_request_response(request_message, session_id=session_id)
        return response.get_payload()
    except Exception as e:
        log.error(f"Error on session {session_id} for tenant {tenant_id}: {e}")
        # Optionally, destroy and recreate the session on failure
        self.destroy_request_response_session(session_id)
        self.kv_store_set(f"session_{tenant_id}", None)
        raise
```

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

### Create a New Git Branch

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/CONTRIBUTING.md

This command creates a new git branch named 'my-fix-branch' starting from the 'master' branch. This is where you will make your changes.

```sh
git checkout -b my-fix-branch master
```

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

### Session Management API

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/guides/broker_request_response.md

APIs for managing dynamic request-response sessions within the Solace AI Connector. These are only available in multi-session mode.

```APIDOC
## POST /solacelabs/solace-ai-connector/session/create

### Description
Creates a new, dynamic request-response session. This method is only available in multi-session mode.

### Method
POST

### Endpoint
/solacelabs/solace-ai-connector/session/create

### Parameters
#### Request Body
- **session_config** (dict) - Optional - A dictionary of configuration values for this session. These values are merged with any defaults.
  - **broker_config** (dict) - Optional - Broker connection details (e.g., `broker_url`, `broker_username`, `broker_password`, `broker_vpn`).
  - **payload_encoding** (str) - Optional - The encoding for the message payload (e.g., `utf-8`, `base64`). Defaults to `"utf-8"`.
  - **payload_format** (str) - Optional - The format of the message payload (e.g., `json`, `text`, `yaml`). Defaults to `"json"`.
  - **request_expiry_ms** (int) - Optional - Timeout in milliseconds for a request to receive a response. Defaults to `30000`.
  - **response_topic_prefix** (str) - Optional - The prefix used for the session's unique reply topic. Defaults to `"reply"`.
  - **response_queue_prefix** (str) - Optional - The prefix used for the session's unique reply queue. Defaults to `"reply-queue"`.
  - **max_concurrent_requests** (int) - Optional - The maximum number of outstanding requests allowed for this session. Defaults to `100`.
  - **user_properties_reply_topic_key** (str) - Optional - The key used to store the reply topic in the request message's user properties. Defaults to `__solace_ai_...`.
  - **response_topic_insertion_expression** (str) - Optional - An expression to insert the reply topic directly into the request message's payload (e.g., `input.payload:reply_to`). Defaults to `""`.

### Request Example
```json
{
  "session_config": {
    "payload_encoding": "base64",
    "request_expiry_ms": 60000
  }
}
```

### Response
#### Success Response (200)
- **session_id** (str) - A unique ID for the newly created session.

#### Response Example
```json
{
  "session_id": "unique-session-id-123"
}
```

---

## DELETE /solacelabs/solace-ai-connector/session/{session_id}

### Description
Destroys a dynamic session and cleans up its resources. It is critical to call this to prevent resource leaks. This method is only available in multi-session mode.

### Method
DELETE

### Endpoint
/solacelabs/solace-ai-connector/session/{session_id}

### Parameters
#### Path Parameters
- **session_id** (str) - Required - The ID of the session to destroy.

### Response
#### Success Response (200)
- **status** (bool) - `True` if the session was found and destroyed, `False` otherwise.

#### Response Example
```json
{
  "status": true
}
```

---

## GET /solacelabs/solace-ai-connector/sessions

### Description
Lists all active dynamic sessions managed by the component. This method is only available in multi-session mode.

### Method
GET

### Endpoint
/solacelabs/solace-ai-connector/sessions

### Response
#### Success Response (200)
- **sessions** (List[dict]) - A list of dictionaries, each containing status information about an active session.

#### Response Example
```json
[
  {
    "session_id": "session-abc",
    "status": "active",
    "created_at": "2023-10-27T10:00:00Z"
  },
  {
    "session_id": "session-xyz",
    "status": "active",
    "created_at": "2023-10-27T10:05:00Z"
  }
]
```
```

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

### Configure Component Specific Settings (YAML)

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/configuration.md

This snippet illustrates how to provide configuration specific to a component using the `component_config` dictionary. The example shows configuration for an 'aggregate' component, including `max_items` and `max_time_ms`.

```yaml
  component_module: aggregate
  component_config:
    max_items: 3
    max_time_ms: 1000

```

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

### Asynchronous Request (Fire-and-Forget) - Requesting Component (Python)

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/guides/broker_request_response.md

Shows how a requesting component can send a message without waiting for a reply, enabling continued processing. This is achieved by setting `wait_for_response=False`.

```python
# In your component's invoke method
# The requesting component sets `wait_for_response=False`.

```

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

### List Request-Response Sessions (Python)

Source: https://github.com/solacelabs/solace-ai-connector/blob/main/docs/guides/broker_request_response.md

Lists all currently active dynamic sessions managed by the component. This function returns a list of dictionaries, where each dictionary contains status information for an active session.

```python
self.list_request_response_sessions() -> List[Dict[str, Any]]
```