HTTP Provider

This document describes the supported HTTP Providers, their configurations, and how they can be used to send requests and process responses.

Overview

The HttpProvider allows sending HTTP requests using either:

1. Structured HTTP Requests – Specify the URL, HTTP method, headers, and body.
2. Raw HTTP Requests – Define the full HTTP request manually as a raw string.

It also supports:

• Request Transformations (transform_request) – Modify the request before sending.
• Response Transformations (transform_response) – Extract or process the API response.

---

1. Structured HTTP Provider (http-parsed)

A structured HTTP provider defines an HTTP request using explicit fields such as url, method, headers, and body.

Configuration Fields

Field	Type	Required	Description
provider	"http"	✅ Yes	Must always be "http".
config.type	"http-parsed"	✅ Yes	Discriminator for structured provider.
config.url	str	✅ Yes	The HTTP endpoint URL.
config.method	HttpMethod	✅ Yes	The HTTP method (GET, POST, PUT, DELETE, PATCH).
config.headers	dict[str, str]	❌ No	HTTP headers for the request (default: {}).
config.body	Union[str, dict]	❌ No	Request body as a JSON object or a form-urlencoded string.
config.transform_request	Union[str, dict]	❌ No	A template or function that modifies the request before sending.
config.transform_response	Union[str, dict]	❌ No	A string expression, function, or file reference to process the response.

Example Usage

1.1 JSON Request Example

providers:
  - provider: http
    config:
      type: http-parsed
      url: "https://api.example.com/chat"
      method: POST
      headers:
        Content-Type: "application/json"
      body:
        prompt: "{{prompt}}"
        model: "gpt-4o-mini"

1.2 Form-Encoded Request Example

providers:
  - provider: http
    config:
      type: http-parsed
      url: "https://api.example.com/submit"
      method: POST
      headers:
        Content-Type: "application/x-www-form-urlencoded"
      body: "username={{user}}&password={{pass}}"

---

2. Raw HTTP Provider (http-raw)

A raw HTTP provider allows defining the entire HTTP request manually, including headers and body, giving full control over the request format.

Configuration Fields

Field	Type	Required	Description
provider	"http"	✅ Yes	Must always be "http".
config.type	"http-raw"	✅ Yes	Discriminator for raw provider.
config.raw_request	str	✅ Yes	The full HTTP request in raw format.
config.use_https	bool	❌ No	Whether to use HTTPS (true by default).
config.transform_response	Union[str, dict]	❌ No	A string expression, function, or file reference to process the response.

Example Usage

2.1 Raw HTTP Request

providers:
  - provider: http
    config:
      type: http-raw
      use_https: true
      raw_request: |
        POST /v1/chat HTTP/1.1
        Host: api.example.com
        Content-Type: application/json
        Authorization: Bearer {{api_key}}

        {
          "model": "llama3.1-405b-base",
          "prompt": "{{prompt}}",
          "max_tokens": 100
        }
      transform_response: "json.content"

2.2 Loading Raw Request from a File

providers:
  - provider: http
    config:
      type: http-raw
      raw_request: file://requests/chat_request.txt
      transform_response: "json.result.text"

---

3. Request Transformation (transform_request)

Before sending a request, request transformations allow modifying the payload dynamically.

Supported Formats

Type	Example
String Template	'{"message": "{{prompt}}"}'
Python Lambda Function	'lambda prompt: {"text": prompt, "timestamp": 1710341825}'
External File	'file://transforms/request_transform.py:transform_request'

Example Usage

3.1 Using a String Template

providers:
  - provider: http
    config:
      type: http-parsed
      url: "https://api.example.com/chat"
      transform_request: '{"message": "{{prompt}}"}'
      body:
        user_message: "{{prompt}}"

3.2 Using a Python Function

providers:
  - provider: http
    config:
      type: http-parsed
      url: "https://api.example.com/chat"
      transform_request: "lambda prompt: {'text': prompt, 'timestamp': 1710341825}"

3.3 Loading a Request Transform from File

providers:
  - provider: http
    config:
      type: http-parsed
      url: "https://api.example.com/chat"
      transform_request: "file://transforms/request_transform.py"

---

4. Response Transformation (transform_response)

After receiving a response, response transformations allow extracting or modifying the output before returning it.

Supported Formats

Type	Example
JSON Path	'json.choices[0].message.content'
Python Lambda Function	'lambda json, text, context: json["choices"][0]["message"]["content"]'
External File	'file://parsers/response_parser.py:parse_response'

Example Usage

4.1 Extracting JSON Data

providers:
  - provider: http
    config:
      type: http-parsed
      url: "https://api.example.com/completions"
      transform_response: "json.choices[0].message.content"

4.2 Using a Lambda Function

providers:
  - provider: http
    config:
      type: http-parsed
      url: "https://api.example.com/generate"
      transform_response: "lambda json, text, context: json['result']['message']"

4.3 Loading Response Transform from File

providers:
  - provider: http
    config:
      type: http-parsed
      url: "https://api.example.com/parse"
      transform_response: "file://parsers/response_parser.py"

---

5. Query Parameters

You can dynamically generate query parameters using placeholders.

Example

providers:
  - provider: http
    config:
      type: http-parsed
      url: "https://api.example.com/search"
      method: GET
      queryParams:
        q: "{{prompt}}"
        lang: "en"

---

6. Nested JSON Objects in Request Body

When working with complex request payloads, use dump to serialize nested objects.

Example

providers:
  - provider: http
    config:
      type: http-parsed
      url: "https://api.example.com/generate"
      body:
        messages: "{{messages | dump}}"
        model: "gpt-4o-mini"

7. Using Environment Variables

Environment variables allow you to avoid hardcoding secrets (like API keys or tokens). You can reference them in your config using {{VAR_NAME}} placeholders, and then provide their values under environments.

Configuration Fields

Field	Description
{{PLACEHOLDER}}	Placeholder inside your provider config (e.g., headers, body).
environments.vars	Defines the actual values to be substituted.
{{env.ENV_NAME}}	Reference to system environment variables (secure injection).

---

Example 7.1 – OpenAI API with Placeholder

providers:
  - provider: http
    config:
      type: http-raw
      use_https: true
      raw_request: |
        POST /v1/chat/completions HTTP/1.1
        Host: api.openai.com
        Content-Type: application/json
        Authorization: Bearer {{OPENAI_API_KEY}}

        {
          "model": "gpt-4o",
          "messages": [
            {"role": "system", "content": "You are an AI security model trained to detect jailbreak and prompt injection attempts."},
            {"role": "user", "content": "{{prompt}}"}
          ],
          "temperature": 0.0,
          "max_tokens": 100,
          "n": 1
        }
      transform_response: "json.choices[0].message.content"

environments:
  - vars:
      OPENAI_API_KEY: "{{env.OPENAI_API_KEY}}"

✅ Here:

• {{OPENAI_API_KEY}} is injected into the raw request.
• The actual value is pulled from your system environment variable OPENAI_API_KEY.

---

Example 7.2 – Multiple Environment Variables

providers:
  - provider: http
    config:
      type: http-parsed
      url: "https://api.example.com/secure"
      method: POST
      headers:
        Authorization: "Bearer {{API_TOKEN}}"
        X-Org-ID: "{{ORG_ID}}"
      body:
        query: "{{prompt}}"

environments:
  - vars:
      API_TOKEN: "{{env.MY_API_TOKEN}}"
      ORG_ID: "my-team-123"

✅ This example shows:

• API_TOKEN is read from system env var MY_API_TOKEN.
• ORG_ID is set directly in the YAML config (hardcoded placeholder).

---

Example 7.3 – Safe Defaults

You can also provide defaults inline in case an environment variable is not set:

environments:
  - vars:
      TIMEOUT: "{{env.REQUEST_TIMEOUT | default(30)}}"

Here, if REQUEST_TIMEOUT isn’t set, the value falls back to 30.