### Starting Plano Orchestrator with Configuration (Shell)

Source: https://docs.planoai.dev/get_started/quickstart

These commands demonstrate how to start the Plano orchestrator using a provided YAML configuration file. It includes instructions for both direct installation and installation via the uv tool.

```shell
$ planoai up plano_config.yaml
# Or if installed with uv tool:
$ uvx planoai up plano_config.yaml
```

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

### Start Plano Service

Source: https://docs.planoai.dev/get_started/quickstart

Starts the Plano service using the generated configuration file. Requires environment variables for API keys to be set.

```bash
$ planoai up plano_config.yaml
# Or if installed with uv tool: uvx planoai up plano_config.yaml
```

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

### Plano Configuration File Example

Source: https://docs.planoai.dev/get_started/quickstart

Defines LLM providers (OpenAI and Anthropic) and a model listener for Plano. This YAML file configures the gateway to route requests to different models.

```yaml
version: v0.3.0

listeners:
  - type: model
    name: model_1
    address: 0.0.0.0
    port: 12000

model_providers:

  - access_key: $OPENAI_API_KEY
    model: openai/gpt-4o
    default: true

  - access_key: $ANTHROPIC_API_KEY
    model: anthropic/claude-sonnet-4-5
```

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

### Starting Plano with Currency Conversion Config (Shell)

Source: https://docs.planoai.dev/get_started/quickstart

This command starts the Plano gateway with the currency conversion configuration. It assumes Plano has been installed and the configuration file is named 'plano_config.yaml'.

```shell
$ planoai up plano_config.yaml
# Or if installed with uv tool: uvx planoai up plano_config.yaml
2024-12-05 16:56:27,979 - planoai.main - INFO - Starting plano cli version: 0.1.5
...
2024-12-05 16:56:28,485 - planoai.utils - INFO - Schema validation successful!
2024-12-05 16:56:28,485 - planoai.main - INFO - Starting plano model server and plano gateway
...
2024-12-05 16:56:51,647 - planoai.core - INFO - Container is healthy!
```

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

### Install Plano CLI with uv

Source: https://docs.planoai.dev/get_started/quickstart

Installs the Plano CLI using the uv package manager. This is the recommended method for fast and reliable Python package management.

```bash
$ curl -LsSf https://astral.sh/uv/install.sh | sh
```

```bash
$ uv tool install planoai==0.4.2
```

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

### Install Plano CLI with pip

Source: https://docs.planoai.dev/get_started/quickstart

Installs the Plano CLI using pip, the traditional Python package installer. This method involves creating a virtual environment and activating it before installation.

```bash
python -m venv venv
source venv/bin/activate   # On Windows, use: venv\Scripts\activate
pip install planoai==0.4.2
```

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

### OpenTelemetry Setup in Python

Source: https://docs.planoai.dev/includes/llms

Provides a Python code example for setting up OpenTelemetry with OTLP gRPC export and Request instrumentation. This involves installing necessary packages, configuring the tracer provider, exporter, and span processor.

```python
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# Define the service name
resource = Resource(attributes={
    "service.name": "customer-support-agent"
})

# Set up the tracer provider and exporter
tracer_provider = TracerProvider(resource=resource)
otlp_exporter = OTLPSpanExporter(endpoint="otel-collector:4317", insecure=True)
span_processor = BatchSpanProcessor(otlp_exporter)
tracer_provider.add_span_processor(span_processor)
trace.set_tracer_provider(tracer_provider)
```

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

### List Supported Currencies Example

Source: https://docs.planoai.dev/includes/llms

A specific example of how to query the chat completions endpoint to get a list of currencies supported for conversion.

```APIDOC
## Querying for Supported Currencies

### Description
Use the chat completions endpoint to request a list of currencies supported for conversion.

### Method
POST

### Endpoint
/v1/chat/completions

### Request Example
```bash
curl --header 'Content-Type: application/json' \
  --data '{"messages": [{"role": "user","content": "show me list of currencies that are supported for conversion"}], "model": "none"}' \
  http://localhost:10000/v1/chat/completions | jq ".choices[0].message.content"
```

### Response Example (content field)
```
"Here is a list of the currencies that are supported for conversion from USD, along with their symbols:\n\n1. AUD - Australian Dollar\n2. BGN - Bulgarian Lev\n3. BRL - Brazilian Real\n4. CAD - Canadian Dollar\n5. CHF - Swiss Franc\n6. CNY - Chinese Renminbi Yuan\n7. CZK - Czech Koruna\n8. DKK - Danish Krone\n9. EUR - Euro\n10. GBP - British Pound\n11. HKD - Hong Kong Dollar\n12. HUF - Hungarian Forint\n13. IDR - Indonesian Rupiah\n14. ILS - Israeli New Sheqel\n15. INR - Indian Rupee\n16. ISK - Icelandic Króna\n17. JPY - Japanese Yen\n18. KRW - South Korean Won\n19. MXN - Mexican Peso\n20. MYR - Malaysian Ringgit\n21. NOK - Norwegian Krone\n22. NZD - New Zealand Dollar\n23. PHP - Philippine Peso\n24. PLN - Polish Złoty\n25. RON - Romanian Leu\n26. SEK - Swedish Krona\n27. SGD - Singapore Dollar\n28. THB - Thai Baht\n29. TRY - Turkish Lira\n30. USD - United States Dollar\n31. ZAR - South African Rand\n\nIf you want to convert USD to any of these currencies, you can select the one you are interested in."
```
```

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

### OpenTelemetry Setup for AI Tracing in Python

Source: https://docs.planoai.dev/guides/observability/tracing

Provides Python code examples for setting up OpenTelemetry instrumentation for AI tracing. This includes installing necessary packages, configuring the tracer provider, and defining an OTLP exporter for sending traces to a collector.

```bash
$ pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp
$ pip install opentelemetry-instrumentation-requests
```

```python
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# Define the service name
resource = Resource(attributes={
    "service.name": "customer-support-agent"
})

# Set up the tracer provider and exporter
tracer_provider = TracerProvider(resource=resource)
otlp_exporter = OTLPSpanExporter(endpoint="otel-collector:4317", insecure=True)
span_processor = BatchSpanProcessor(otlp_exporter)
tracer_provider.add_span_processor(span_processor)
trace.set_tracer_provider(tracer_provider)
```

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

### List Supported Currencies

Source: https://docs.planoai.dev/get_started/quickstart

This is a specific use case of the Chat Completions API, demonstrating how to query for a list of currencies supported by the gateway.

```APIDOC
## GET Supported Currencies (via Chat Completions)

### Description
Retrieves a list of currencies that the Plano AI gateway supports for conversion.

### Method
POST

### Endpoint
`http://localhost:10000/v1/chat/completions`

### Parameters
#### Query Parameters
None

#### Request Body
- **messages** (array) - Required - An array containing a single user message requesting the list of supported currencies.
  - **role** (string) - Must be 'user'.
  - **content** (string) - Must be "show me list of currencies that are supported for conversion".
- **model** (string) - Required - Specifies the model to use (e.g., 'none' for this example).

### Request Example
```json
{
  "messages": [
    {"role": "user", "content": "show me list of currencies that are supported for conversion"}
  ],
  "model": "none"
}
```

### Response
#### Success Response (200)
- **choices** (array) - Contains the AI's response.
  - **message** (object)
    - **content** (string) - A formatted list of supported currencies and their symbols.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "content": "Here is a list of the currencies that are supported for conversion from USD, along with their symbols:\n\n1. AUD - Australian Dollar\n2. BGN - Bulgarian Lev\n... (list continues) ...\n31. ZAR - South African Rand\n\nIf you want to convert USD to any of these currencies, you can select the one you are interested in."
      }
    }
  ]
}
```
```

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

### Deterministic API Calls Configuration

Source: https://docs.planoai.dev/get_started/quickstart

This configuration sets up Plano for deterministic API calls using prompt targets, specifically for currency exchange functionality.

```APIDOC
## Deterministic API Calls with Prompt Targets

### Description
This section details the configuration for Plano's deterministic API calling feature using prompt targets. It focuses on building a currency exchange backend powered by an external API.

### Method
N/A (Configuration file)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Plano Configuration for Currency Conversion

### Description
This `plano_config.yaml` file defines listeners, model providers, prompt targets for currency exchange and supported currencies, and external endpoints.

### Method
N/A (Configuration file)

### Endpoint
N/A

### Parameters
#### Listeners
- **ingress_traffic** (object)
  - **address** (string) - Optional - `0.0.0.0`
  - **port** (integer) - Required - `10000`
  - **message_format** (string) - Required - `openai`
  - **timeout** (string) - Required - `30s`

#### Model Providers
- **access_key** (string) - Required - `$OPENAI_API_KEY`
- **model** (string) - Required - `openai/gpt-4o`

#### System Prompt
- **system_prompt** (string) - Optional - `You are a helpful assistant.`

#### Prompt Targets
- **name** (string) - Required - Name of the prompt target (e.g., `currency_exchange`, `get_supported_currencies`).
- **description** (string) - Required - Description of the prompt target.
- **parameters** (array of objects) - Optional (for `get_supported_currencies`) - Parameters for the target.
  - **name** (string) - Required - Parameter name (e.g., `currency_symbol`).
  - **description** (string) - Required - Description of the parameter.
  - **required** (boolean) - Required - Whether the parameter is required (`true` or `false`).
  - **type** (string) - Required - Data type of the parameter (e.g., `str`).
  - **in_path** (boolean) - Optional - If the parameter is part of the path (`true` or `false`).
- **endpoint** (object) - Required.
  - **name** (string) - Required - Name of the endpoint (e.g., `frankfurther_api`).
  - **path** (string) - Required - The API path, including placeholders for parameters (e.g., `/v1/latest?base=USD&symbols={currency_symbol}`).
- **system_prompt** (string) - Optional - A system prompt specific to this target.

#### Endpoints
- **frankfurther_api** (object)
  - **endpoint** (string) - Required - The host and port of the external API (e.g., `api.frankfurter.dev:443`).
  - **protocol** (string) - Required - The protocol to use (e.g., `https`).

### Request Example
```yaml
version: v0.1.0

listeners:
  ingress_traffic:
    address: 0.0.0.0
    port: 10000
    message_format: openai
    timeout: 30s

 model_providers:
   - access_key: $OPENAI_API_KEY
     model: openai/gpt-4o

 system_prompt: |
   You are a helpful assistant.

 prompt_targets:
   - name: currency_exchange
     description: Get currency exchange rate from USD to other currencies
     parameters:
       - name: currency_symbol
         description: the currency that needs conversion
         required: true
         type: str
         in_path: true
     endpoint:
       name: frankfurther_api
       path: /v1/latest?base=USD&symbols={currency_symbol}
     system_prompt: |
       You are a helpful assistant. Show me the currency symbol you want to convert from USD.

   - name: get_supported_currencies
     description: Get list of supported currencies for conversion
     endpoint:
       name: frankfurther_api
       path: /v1/currencies

 endpoints:
   frankfurther_api:
     endpoint: api.frankfurter.dev:443
     protocol: https
```

## Starting Plano with Currency Conversion Config

### Description
This describes how to start the Plano service using the currency conversion configuration file.

### Method
CLI command

### Endpoint
N/A

### Parameters
- **plano_config.yaml** (file) - Required - The path to the currency conversion configuration file.

### Request Example
```bash
$ planoai up plano_config.yaml
# Or if installed with uv tool: uvx planoai up plano_config.yaml
```

### Response
Once the gateway is up, you can start interacting with it at port 10000 using the OpenAI chat completion API. Some sample queries you can ask include: `what is currency rate for gbp?` or `show me list of currencies for conversion`.
```

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

### Minimal Orchestration Configuration

Source: https://docs.planoai.dev/get_started/quickstart

This configuration sets up Plano to route requests to flight and hotel agents and enables an agent listener on port 8001.

```APIDOC
## Minimal Orchestration Configuration

### Description
This configuration sets up Plano to route requests to flight and hotel agents and enables an agent listener on port 8001. It defines agents, model providers, and listeners for orchestration.

### Method
N/A (Configuration file)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Starting Plano with Minimal Orchestration

### Description
This describes how to start the Plano service using the minimal orchestration configuration file.

### Method
CLI command

### Endpoint
N/A

### Parameters
- **plano_config.yaml** (file) - Required - The path to the minimal orchestration configuration file.

### Request Example
```bash
$ planoai up plano_config.yaml
# Or if installed with uv tool:
$ uvx planoai up plano_config.yaml
```

### Response
Plano will start the orchestrator and expose an agent listener on port 8001.

## Sending a Prompt to the Orchestrator

### Description
Send a prompt to the Plano orchestrator via the OpenAI-compatible chat completions API. The orchestrator will analyze the prompt and route it to the appropriate agent.

### Method
POST

### Endpoint
`http://localhost:8001/v1/chat/completions`

### Parameters
#### Header Parameters
- **Content-Type** (string) - Required - `application/json`

#### Request Body
- **messages** (array of objects) - Required - The conversation messages.
  - **role** (string) - Required - Role of the message sender ('user', 'assistant', etc.).
  - **content** (string) - Required - The content of the message.
- **model** (string) - Required - The model to use for the completion (e.g., `openai/gpt-4o`).

### Request Example
```json
{
  "messages": [
    {"role": "user", "content": "Find me flights from SFO to JFK tomorrow"}
  ],
  "model": "openai/gpt-4o"
}
```

### Response
#### Success Response (200)
An object containing the chat completion response from the routed agent or LLM.

#### Response Example
(Example response structure depends on the agent's output)
```

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

### Plano Configuration File Example

Source: https://docs.planoai.dev/includes/llms

Example of a plano_config.yaml file defining LLM providers and listeners. This configuration specifies OpenAI as a model provider and sets up a model listener on port 12000.

```yaml
version: v0.3.0

listeners:
  - type: model
    name: model_1
    address: 0.0.0.0
    port: 12000

model_providers:

  - access_key: $OPENAI_API_KEY
    model: openai/gpt-4o
    default: true
```

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

### Start Plano Orchestrator with UV Tool

Source: https://docs.planoai.dev/includes/llms

This command starts the Plano orchestrator using the uvx tool with a specified configuration file. It exposes an agent listener on port 8001 for incoming requests.

```bash
$ uvx planoai up plano_config.yaml
```

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

### List Supported Currencies via curl

Source: https://docs.planoai.dev/get_started/quickstart

This snippet demonstrates how to use curl to query the Plano AI gateway for a list of supported currencies. It includes the necessary headers, a JSON payload requesting the list, and uses jq to parse the response and display the currency information.

```bash
$ curl --header 'Content-Type: application/json' \
  --data '{"messages": [{"role": "user","content": "show me list of currencies that are supported for conversion"}], "model": "none"}' \
  http://localhost:10000/v1/chat/compositions | jq ".choices[0].message.content"
```

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

### Interact with Plano Gateway using OpenAI Python Client

Source: https://docs.planoai.dev/get_started/quickstart

Uses the OpenAI Python client to interact with the Plano gateway. Sets the base_url to the Plano endpoint and uses a placeholder model.

```python
from openai import OpenAI

# Use the OpenAI client as usual
client = OpenAI(
  # No need to set a specific openai.api_key since it's configured in Plano's gateway
  api_key='--',
  # Set the OpenAI API base URL to the Plano gateway endpoint
  base_url="http://127.0.0.1:12000/v1"
)

response = client.chat.completions.create(
    # we select model from plano_config file
    model="--",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
)

print("OpenAI Response:", response.choices[0].message.content)
```

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

### Plano Configuration for Deterministic API Calls (YAML)

Source: https://docs.planoai.dev/get_started/quickstart

This YAML configuration sets up Plano for deterministic API calls using prompt targets. It defines listeners, model providers, system prompts, prompt targets for currency exchange, and external endpoints.

```yaml
version: v0.1.0

listeners:
  ingress_traffic:
    address: 0.0.0.0
    port: 10000
    message_format: openai
    timeout: 30s

 model_providers:
   - access_key: $OPENAI_API_KEY
     model: openai/gpt-4o

 system_prompt: |
   You are a helpful assistant.

 prompt_targets:
   - name: currency_exchange
     description: Get currency exchange rate from USD to other currencies
     parameters:
       - name: currency_symbol
         description: the currency that needs conversion
         required: true
         type: str
         in_path: true
     endpoint:
       name: frankfurther_api
       path: /v1/latest?base=USD&symbols={currency_symbol}
     system_prompt: |
       You are a helpful assistant. Show me the currency symbol you want to convert from USD.

   - name: get_supported_currencies
     description: Get list of supported currencies for conversion
     endpoint:
       name: frankfurther_api
       path: /v1/currencies

 endpoints:
   frankfurther_api:
     endpoint: api.frankfurter.dev:443
     protocol: https
```

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

### Start Plano Docker Services

Source: https://docs.planoai.dev/includes/llms

Commands to start the Plano services defined in `docker-compose.yml`. It includes setting required environment variables and using `docker compose up -d` for detached mode.

```bash
# Set required environment variables and start services
OPENAI_API_KEY=xxx ANTHROPIC_API_KEY=yyy docker compose up -d
```

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

### Python Example of Calling a Function

Source: https://docs.planoai.dev/includes/llms

Demonstrates how to call a Python function with specified arguments and print the result. This example assumes the existence of a 'get_weather' function.

```python
weather_info = get_weather("Seattle, WA", "celsius")
print(weather_info)
```

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

### OpenAI Provider Configuration Examples

Source: https://docs.planoai.dev/concepts/llm_providers/supported_providers

Examples for configuring OpenAI models in Plano. It demonstrates setting up the latest models like GPT-5.2 and GPT-5, and highlights that any model from OpenAI's API can be used. The 'default: true' option is shown for setting a primary model.

```yaml
llm_providers:
  # Latest models (examples - use any OpenAI chat model)
  - model: openai/gpt-5.2
    access_key: $OPENAI_API_KEY
    default: true

  - model: openai/gpt-5
    access_key: $OPENAI_API_KEY

  # Use any model name from OpenAI's API
  - model: openai/gpt-4o
    access_key: $OPENAI_API_KEY
```

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

### Install OpenAI SDK with Python

Source: https://docs.planoai.dev/concepts/llm_providers/client_libraries

Installs the OpenAI Python SDK using pip. This is a prerequisite for using the OpenAI SDK with Plano's gateway.

```shell
pip install openai
```

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

### Install Anthropic SDK (Python)

Source: https://docs.planoai.dev/concepts/llm_providers/client_libraries

This command installs the Anthropic Python SDK, which is necessary for interacting with Plano's Anthropic-compatible endpoint. This SDK allows seamless integration with various LLM providers through Plano's state management.

```bash
pip install anthropic
```

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

### Start Plano with Currency Conversion Configuration

Source: https://docs.planoai.dev/includes/llms

This command initiates the Plano orchestrator using a specific configuration file designed for currency conversion tasks. It loads the defined listeners, model providers, and prompt targets.

```bash
$ planoai up plano_config.yaml
```

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

### Plano Configuration Example

Source: https://docs.planoai.dev/includes/llms

A basic Plano configuration file in YAML format. It sets up the listener address and port, and defines LLM providers, specifically configuring OpenAI with an access key and model.

```yaml
version: v0.1
listener:
  address: 127.0.0.1
  port: 8080 #If you configure port 443, you'll need to update the listener with tls_certificates
  message_format: huggingface

# Centralized way to manage LLMs, manage keys, retry logic, failover and limits in a central way
llm_providers:
  - name: OpenAI
    provider: openai
    access_key: $OPENAI_API_KEY
    model: gpt-3.5-turbo
    default: true
```

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

### Get Exchange Rate via curl

Source: https://docs.planoai.dev/get_started/quickstart

This snippet shows how to use curl to send a query to the Plano AI gateway to get an exchange rate. It specifies the content type as JSON, provides a JSON payload with a user message and model, and directs the output through jq to extract the content of the message.

```bash
$ curl --header 'Content-Type: application/json' \
  --data '{"messages": [{"role": "user","content": "what is exchange rate for gbp"}], "model": "none"}' \
  http://localhost:10000/v1/chat/completions | jq ".choices[0].message.content"
```

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

### Python OpenTelemetry Instrumentation Example

Source: https://docs.planoai.dev/guides/observability/tracing

This snippet demonstrates how to instrument a Python application using OpenTelemetry to capture trace data. It shows basic setup for generating and managing spans, which are fundamental units of work in distributed tracing. Ensure OpenTelemetry is installed in your Python environment.

```python
from opentelemetry import trace

# Initialize tracer provider (requires configuration)
# tracer_provider = ...
# trace.set_tracer_provider(tracer_provider)

tracer = trace.get_tracer(__name__)

def my_function():
    with tracer.start_as_current_span("my_operation"):
        # Your code here
        print("Performing operation...")
        # ... more operations ...

my_function()

```

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

### Switching Capabilities with Python Client

Source: https://docs.planoai.dev/includes/llms

Demonstrates how to switch to a different capability by specifying the model name in the client.chat.completions.create method. This example uses Python and the OpenAI client library.

```python
response = client.chat.completions.create(
    model="arch.reasoning.v1",  # Points to gpt-4o
    messages=[{"role": "user", "content": "Solve this complex problem..."}]
)
```

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

### Start Plano Docker Services and Perform Runtime Checks

Source: https://docs.planoai.dev/resources/deployment

These commands demonstrate how to start the Plano Docker services in detached mode and then monitor their health and logs. Setting environment variables directly in the command line is shown for initial setup.

```bash
# Set required environment variables and start services
OPENAI_API_KEY=xxx ANTHROPIC_API_KEY=yyy docker compose up -d

# Check container health and logs
docker compose ps
docker compose logs -f plano
```

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

### Define Weather Agent Description for Plano

Source: https://docs.planoai.dev/guides/orchestration

This example shows how to write an effective description for the `weather_agent` in Plano. It includes a clear introduction, lists specific capabilities, mentions the API used (Open-Meteo API), and details how it handles context and query patterns.

```yaml
- id: weather_agent
  description: |

    WeatherAgent is a specialized AI assistant for real-time weather information
    and forecasts. It provides accurate weather data for any city worldwide using
    the Open-Meteo API, helping travelers plan their trips with up-to-date weather
    conditions.

    Capabilities:
      * Get real-time weather conditions and multi-day forecasts for any city worldwide
      * Provides current temperature, weather conditions, sunrise/sunset times

```

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

### Configure Qwen (Alibaba) Models

Source: https://docs.planoai.dev/concepts/llm_providers/supported_providers

Configuration examples for Qwen models from Alibaba Cloud, including Qwen3 and Qwen3-Coder. Requires an API key (e.g., DASHSCOPE_API_KEY) and a base URL, which can vary for different regions or services.

```yaml
llm_providers:
  # Single deployment
  - model: qwen/qwen3
    access_key: $DASHSCOPE_API_KEY
    base_url: https://dashscope.aliyuncs.com

  # Multiple deployments
  - model: qwen/qwen3-coder
    access_key: $DASHSCOPE_API_KEY
    base_url: "https://dashscope-intl.aliyuncs.com"
```

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

### Configure Amazon Bedrock LLM Provider

Source: https://docs.planoai.dev/includes/llms

This configuration example outlines how to set up the Amazon Bedrock provider. It involves specifying the model ID for communication, and Plano automatically constructs the necessary API endpoints for both streaming and non-streaming requests.

```YAML
llm_providers:
  - model: amazon_bedrock/anthropic.claude-3-sonnet-20240229-v1:0
    access_key: $AWS_ACCESS_KEY_ID
    secret_access_key: $AWS_SECRET_ACCESS_KEY
    region_name: us-east-1
```

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

### Interact with Plano Gateway using cURL

Source: https://docs.planoai.dev/get_started/quickstart

Sends a chat completion request to the Plano gateway via cURL. Plano will select a default model if 'none' is specified.

```bash
$ curl --header 'Content-Type: application/json' \
  --data '{"messages": [{"role": "user","content": "What is the capital of France?"}], "model": "none"}' \
  http://localhost:12000/v1/chat/completions
```

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

### Chat Completions API

Source: https://docs.planoai.dev/get_started/quickstart

This endpoint allows you to send chat messages to the AI model and receive a response. It can be used for various queries, such as asking for exchange rates or requesting a list of supported currencies.

```APIDOC
## POST /v1/chat/completions

### Description
Sends a chat message to the AI model and retrieves a text-based response.

### Method
POST

### Endpoint
`http://localhost:10000/v1/chat/completions`

### Parameters
#### Query Parameters
None

#### Request Body
- **messages** (array) - Required - An array of message objects, where each object has a 'role' (e.g., 'user') and 'content' (the message text).
- **model** (string) - Required - Specifies the model to use (e.g., 'none' for this example).

### Request Example
```json
{
  "messages": [
    {"role": "user", "content": "what is exchange rate for gbp"}
  ],
  "model": "none"
}
```

### Response
#### Success Response (200)
- **choices** (array) - Contains the AI's response.
  - **message** (object)
    - **content** (string) - The AI-generated text response.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "content": "As of the date provided in your context, December 5, 2024, the exchange rate for GBP (British Pound) from USD (United States Dollar) is 0.78558. This means that 1 USD is equivalent to 0.78558 GBP."
      }
    }
  ]
}
```
```

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

### Sending a Prompt to Plano Orchestrator (cURL)

Source: https://docs.planoai.dev/get_started/quickstart

This cURL command sends a request to the Plano orchestrator's chat completions API. The orchestrator will analyze the prompt and route it to the appropriate agent based on intent.

```shell
$ curl --header 'Content-Type: application/json' \
  --data '{"messages": [{"role": "user","content": "Find me flights from SFO to JFK tomorrow"}], "model": "openai/gpt-4o"}' \
  http://localhost:8001/v1/chat/completions
```

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

### Minimal Plano Orchestration Configuration (YAML)

Source: https://docs.planoai.dev/get_started/quickstart

This YAML configuration sets up Plano Orchestrator to route calls to two HTTP services: one for flights and one for hotels. It also configures model providers and an agent listener.

```yaml
version: v0.1.0

agents:
  - id: flight_agent
    url: http://host.docker.internal:10520  # your flights service
  - id: hotel_agent
    url: http://host.docker.internal:10530  # your hotels service

model_providers:
  - model: openai/gpt-4o
    access_key: $OPENAI_API_KEY

listeners:
  - type: agent
    name: travel_assistant
    port: 8001
    router: plano_orchestrator_v1
    agents:
      - id: flight_agent
        description: Search for flights and provide flight status.
      - id: hotel_agent
        description: Find hotels and check availability.

tracing:
  random_sampling: 100
```

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

### Prepare Weather Context and Generate LLM Response (Python)

Source: https://docs.planoai.dev/includes/llms

Prepares weather context based on user messages and retrieves live weather data. It constructs a detailed message history for the LLM, including system instructions and conversation context, then streams the LLM's response. Utilizes 'openai_client_via_plano' for LLM interaction and logs any generation errors.

```python
async def generate_weather_response(request, messages, request_body):
    last_user_msg = get_last_user_content(messages)
    days = 1

    if "forecast" in last_user_msg or "week" in last_user_msg:
        days = 7
    elif "tomorrow" in last_user_msg:
        days = 2

    import re

    day_match = re.search(r"(\d{1,2})\s+day", last_user_msg)
    if day_match:
        requested_days = int(day_match.group(1))
        days = min(requested_days, 16)

    weather_data = await get_weather_data(request, messages, days)

    forecast_type = "forecast" if days > 1 else "current weather"
    weather_context = f"\n\nWeather data for {weather_data['location']} ({forecast_type}):\n{json.dumps(weather_data, indent=2)}"

    instructions = """You are a weather assistant in a multi-agent system. You will receive weather data in JSON format with these fields:\n\n    - \"location\": City name\n    - \"forecast\": Array of weather objects, each with date, day_name, temperature_c, temperature_f, temperature_max_c, temperature_min_c, weather_code, sunrise, sunset\n    - weather_code: WMO code (0=clear, 1-3=partly cloudy, 45-48=fog, 51-67=rain, 71-86=snow, 95-99=thunderstorm)\n\n    Your task:\n    1. Present the weather/forecast clearly for the location\n    2. For single day: show current conditions\n    3. For multi-day: show each day with date and conditions\n    4. Include temperature in both Celsius and Fahrenheit\n    5. Describe conditions naturally based on weather_code\n    6. Use conversational language\n\n    Important: If the conversation includes information from other agents (like flight details), acknowledge and build upon that context naturally. Your primary focus is weather, but maintain awareness of the full conversation.\n\n    Remember: Only use the provided data. If fields are null, mention data is unavailable."""

    response_messages = [{"role": "system", "content": instructions}]

    for i, msg in enumerate(messages):
        if i == len(messages) - 1 and msg.get("role") == "user":
            response_messages.append({"role": "user", "content": msg.get("content") + weather_context})
        else:
            response_messages.append({"role": msg.get("role"), "content": msg.get("content")})

    try:
        ctx = extract(request.headers)
        extra_headers = {"x-envoy-max-retries": "3"}
        inject(extra_headers, context=ctx)

        stream = await openai_client_via_plano.chat.completions.create(
            model=WEATHER_MODEL,
            messages=response_messages,
            temperature=request_body.get("temperature", 0.7),
            max_tokens=request_body.get("max_tokens", 1000),
            stream=True,
            extra_headers=extra_headers,
        )

        async for chunk in stream:
            if chunk.choices:
                yield f"data: {chunk.model_dump_json()}\n\n"

        yield "data: [DONE]\n\n"

    except Exception as e:
        logger.error(f"Error generating weather response: {e}")
```

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

### Configure Zhipu AI GLM Models

Source: https://docs.planoai.dev/concepts/llm_providers/supported_providers

Configuration examples for Zhipu AI GLM models. This setup includes the latest GLM-4.6, GLM-4.5, and GLM-4.5 Air models. An API key from the Zhipu AI Platform is required.

```yaml
llm_providers:
  # Latest GLM models
  - model: zhipu/glm-4.6
    access_key: $ZHIPU_API_KEY

  - model: zhipu/glm-4.5
    access_key: $ZHIPU_API_KEY

  - model: zhipu/glm-4.5-air
    access_key: $ZHIPU_API_KEY
```

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

### Extract Flight Route using OpenAI

Source: https://docs.planoai.dev/includes/llms

This function extracts flight origin, destination, and date from a conversation using a specified OpenAI model. It employs a structured prompt with explicit rules and examples to guide the LLM. The function processes the last five messages for context and parses the LLM's JSON output, returning a dictionary with extracted flight details. It includes error handling and cleanup for JSON output.

```python
async def extract_flight_route(messages: list, request: Request) -> dict:
    """Extract origin, destination, and date from conversation using LLM."""

    extraction_prompt = """Extract flight origin, destination cities, and travel date from the conversation.

    Rules:
    1. Look for patterns: "flight from X to Y", "flights to Y", "fly from X"
    2. Extract dates like "tomorrow", "next week", "December 25", "12/25", "on Monday"
    3. Use conversation context to fill in missing details
    4. Return JSON: {"origin": "City" or null, "destination": "City" or null, "date": "YYYY-MM-DD" or null}

    Examples:
    - "Flight from Seattle to Atlanta tomorrow" -> {"origin": "Seattle", "destination": "Atlanta", "date": "2025-12-24"}
    - "What flights go to New York?" -> {"origin": null, "destination": "New York", "date": null}
    - "Flights to Miami on Christmas" -> {"origin": null, "destination": "Miami", "date": "2025-12-25"}
    - "Show me flights from LA to NYC next Monday" -> {"origin": "LA", "destination": "NYC", "date": "2025-12-30"}

    Today is December 23, 2025. Extract flight route and date:"""

    try:
        ctx = extract(request.headers)
        extra_headers = {}
        inject(extra_headers, context=ctx)

        response = await openai_client_via_plano.chat.completions.create(
            model=EXTRACTION_MODEL,
            messages=[
                {"role": "system", "content": extraction_prompt},
                *[{"role": msg.get("role"), "content": msg.get("content")} for msg in messages[-5:]],
            ],
            temperature=0.1,
            max_tokens=100,
            extra_headers=extra_headers if extra_headers else None,
        )

        result = response.choices[0].message.content.strip()
        if "```json" in result:
            result = result.split("```json")[1].split("```")[0].strip()
        elif "```" in result:
            result = result.split("```")[1].split("```")[0].strip()

        route = json.loads(result)
        return {
            "origin": route.get("origin"),
            "destination": route.get("destination"),
            "date": route.get("date"),
        }
    except Exception as e:
        logger.error(f"Error extracting flight route: {e}")
        return {"origin": None, "destination": None, "date": None}
```