Merge pull request #1 from jentic/docs/readme-restructure

MichaelCordner · web-flow · commit 69d3da85c569 · 2025-07-16T20:13:19.000+01:00
feat(docs): restructure project documentation
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 the Arazzo Engine project contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,251 +1,40 @@
-This repository contains projects related to the creation, verification and execution of Arazzo Workfows.
+[![Discord](https://img.shields.io/badge/JOIN%20OUR%20DISCORD-COMMUNITY-7289DA?style=plastic&logo=discord&logoColor=white)](https://discord.gg/TdbWXZsUSm)
 
-# Arazzo Runner [Beta]
+# Arazzo Engine
 
-The Arazzo Runner is a workflow execution engine that processes and executes API workflows defined in the Arazzo format and individual API calls defined in OpenAPI specifications.
+Welcome to the Arazzo Engine repository! This project is dedicated to building a powerful suite of tools for the **[Arazzo Specification](https://www.openapis.org/arazzo-specification)**, a new open-source standard from the **OpenAPI Initiative** for describing and executing complex sequences of API calls.
 
-## Usage
+As a community-driven specification under the Linux Foundation, Arazzo is poised to revolutionize how we orchestrate and automate API interactions. This repository provides a set of open-source tools to bring Arazzo workflows to life.
 
-### Execute a Workflow
-```python
-from arazzo_runner import ArazzoRunner
+## What is Arazzo?
 
-runner = ArazzoRunner.from_arazzo_path("../../workflows/discord.com/workflows.arazzo.json")
+Arazzo is an official specification from the OpenAPI Initiative, joining the well-known OpenAPI Specification (OAS) and the new Overlay Specification. While OAS excels at describing individual APIs, **Arazzo defines a standard, language-agnostic way to orchestrate calls across one or more APIs into a workflow.**
 
-result = runner.execute_workflow("workflowId", {"param1": "value1"})
-```
+It makes API use cases human- and machine-readable, removing the guesswork and enabling powerful automation for:
+*   Interactive workflow documentation
+*   Code and SDK generation
+*   Automated testing
+*   Deterministic API invocation by AI agents
 
-### Display Authentication Options
-```python
-from arazzo_runner import ArazzoRunner
+This project, the Arazzo Engine, provides tools to harness the power of this new standard.
 
-runner = ArazzoRunner.from_arazzo_path("../../workflows/discord.com/workflows.arazzo.json")
+## What's in this Repository?
 
-print(runner.get_env_mappings())
-```
+This repository is home to a growing collection of tools for the Arazzo ecosystem. Our first tool is the **Arazzo Runner**.
 
-### Execute a Single OpenAPI Operation
-```python
-from arazzo_runner import ArazzoRunner
-# Execute a single OpenAPI operation with an operationId
-result = runner.execute_operation("operationId", {"param1": "value1"})
+### [Arazzo Runner](./runner/README.md)
 
-# Execute a single OpenAPI operation by path
-result = runner.execute_operation("GET /users/@me/guilds", {"param1": "value1"})
-```
+The Arazzo Runner is a command-line tool and Python library that can execute Arazzo workflows. It is the engine that powers the execution of your Arazzo definitions, handling everything from authentication and parameter passing to conditional logic and error handling.
 
-### Create a Runner with a Custom Base Path
-```python
-# Create a runner instance with a custom base path for resolving OpenAPI file paths
-runner_with_base_path = ArazzoRunner.from_arazzo_path(
-    "./my/arazzo.yaml", 
-    base_path="./my/source/description/base"
-)
-```
+[**Learn more about the Arazzo Runner here.**](./runner/README.md)
 
-## Authentication
+## Join the Community!
+The Arazzo specification and the tools in this repository are open-source and community-driven. We believe that the best way to build a powerful and flexible workflow standard is to do it in the open, with the help of the entire OpenAPI community.
+Whether you're an API developer, a DevOps engineer, or just someone who is passionate about automation, we invite you to get involved. Here are a few ways you can contribute:
+*   **Try out the Arazzo Runner:** Use it to automate your own API workflows and give us feedback.
+*   **Contribute to the code:** Help us build new features, fix bugs, and improve the existing tools.
+*   **Improve the documentation:** Help us make the Arazzo specification and our tools easier to understand and use.
+*   **Spread the word:** Tell your friends and colleagues about Arazzo and the Arazzo Engine.
 
-Credentials are resolved from environment variables defined by the Arazzo Runner based on the Arazzo or OpenAPI file. You can see the authentication options by using `runner.get_env_mappings` or the `show-env-mappings` command line tool defined below.
+We're excited to have you on board. Let's build the future of API orchestration together!
 
-The Arazzo Runner supports various authentication methods defined in OpenAPI specifications:
-
-- **API Key**: Header, Query, or Cookie API keys
-- **OAuth2**: Some OAuth2 Flows (Client Credentials, Password)
-- **HTTP**: Basic and Bearer Authentication
-
-### Auth Methods Not Yet Supported
-- **OAuth2**: Authorization Code, Implicit
-- **OpenID**: OpenID Connect
-- **Custom**: Custom Authentication Schemes
-
-## Command Line Usage
-
-Usage:
-```sh
-uvx arazzo-runner <command> [command-specific arguments] [global options]
-```
-
-**Commands:**
-
-1.  **`show-env-mappings`**: Show environment variable mappings for authentication based on an Arazzo or OpenAPI file.
-    ```sh
-    uvx arazzo-runner show-env-mappings [arazzo_path | --openapi-path PATH]
-    ```
-    -   `arazzo_path`: Path to the Arazzo YAML file (use this OR --openapi-path).
-    -   `--openapi-path PATH`: Path to the OpenAPI spec file (use this OR arazzo_path).
-    *One of the path arguments is required.*
-
-2.  **`execute-workflow`**: Execute a workflow defined in an Arazzo file.
-    ```sh
-    uvx arazzo-runner execute-workflow <arazzo_path> --workflow-id <workflow_id> [--inputs <json_string>]
-    ```
-    -   `arazzo_path`: *Required*. Path to the Arazzo YAML file containing the workflow.
-    -   `--workflow-id WORKFLOW_ID`: *Required*. ID of the workflow to execute.
-    -   `--inputs INPUTS`: Optional JSON string of workflow inputs (default: `{}`).
-
-3.  **`execute-operation`**: Execute a single API operation directly from an OpenAPI specification (or an Arazzo file for context).
-    ```sh
-    uvx arazzo-runner execute-operation [--arazzo-path PATH | --openapi-path PATH] [--operation-id ID | --operation-path PATH_METHOD] [--inputs <json_string>]
-    ```
-    -   `--arazzo-path PATH`: Path to an Arazzo file (provides context, use this OR --openapi-path).
-    -   `--openapi-path PATH`: Path to the OpenAPI spec file (use this OR --arazzo-path).
-        *One of the path arguments is required.*
-    -   `--operation-id ID`: The `operationId` from the OpenAPI spec (use this OR --operation-path).
-    -   `--operation-path PATH_METHOD`: The HTTP method and path (e.g., 'GET /users/{id}') from the OpenAPI spec (use this OR --operation-id).
-        *One of the operation identifiers is required.*
-    -   `--inputs INPUTS`: Optional JSON string of operation inputs (parameters, request body) (default: `{}`).
-
-4.  **`list-workflows`**: List all available workflows defined in an Arazzo file.
-    ```sh
-    uvx arazzo-runner list-workflows <arazzo_path>
-    ```
-    -   `arazzo_path`: *Required*. Path to the Arazzo YAML file.
-
-5.  **`describe-workflow`**: Show details of a specific workflow, including its summary, inputs, steps, and outputs.
-    ```sh
-    uvx arazzo-runner describe-workflow <arazzo_path> --workflow-id <workflow_id>
-    ```
-    -   `arazzo_path`: *Required*. Path to the Arazzo YAML file containing the workflow.
-    -   `--workflow-id WORKFLOW_ID`: *Required*. ID of the workflow to describe.
-
-6.  **`generate-example`**: Generate an example CLI command to execute a specified workflow, including placeholder inputs.
-    ```sh
-    uvx arazzo-runner generate-example <arazzo_path> --workflow-id <workflow_id>
-    ```
-    -   `arazzo_path`: *Required*. Path to the Arazzo YAML file containing the workflow.
-    -   `--workflow-id WORKFLOW_ID`: *Required*. ID of the workflow to generate an example for.
-
-
-**Global Options:**
-- `--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}`: Set the logging level (default: INFO).
-
-
-**Examples:**
-
-```sh
-# Show environment variable mappings using an Arazzo file
-uvx arazzo-runner show-env-mappings ./tests/fixtures/discord/discord.arazzo.yaml
-
-# Show environment variable mappings using an OpenAPI file
-uvx arazzo-runner show-env-mappings --openapi-path ./tests/fixtures/discord/discord.openapi.json
-
-# Execute a workflow
-uvx arazzo-runner execute-workflow ./tests/fixtures/discord/discord.arazzo.yaml --workflow-id getUserInfoAndSendMessage --inputs '{\"recipient_id\": \"1234567890\", \"message_content\": \"Hello!\"}'
-
-# Execute a specific operation using its operationId and an OpenAPI file
-uvx arazzo-runner execute-operation --openapi-path ./tests/fixtures/discord/discord.openapi.json --operation-id list_my_guilds --inputs '{}'
-
-# Execute a specific operation using its path/method and an Arazzo file (for context)
-uvx arazzo-runner execute-operation --arazzo-path ./tests/fixtures/discord/discord.arazzo.yaml --operation-path 'GET /users/@me/guilds' --inputs '{}' --log-level DEBUG
-
-# List all available workflows
-uvx arazzo-runner list-workflows ./tests/fixtures/discord/discord.arazzo.yaml
-
-# Describe a specific workflow
-uvx arazzo-runner describe-workflow ./tests/fixtures/discord/discord.arazzo.yaml --workflow-id getUserInfoAndSendMessage
-
-# Generate an example CLI command to execute a workflow
-uvx arazzo-runner generate-example ./tests/fixtures/discord/discord.arazzo.yaml --workflow-id getUserInfoAndSendMessage
-```
-
-**Help:**
-```sh
-# General help
-uvx arazzo-runner --help
-
-# Help for a specific command (e.g., execute-operation)
-uvx arazzo-runner execute-operation --help
-```
-
-## Server URL Configuration
-
-Arazzo Runner supports dynamic server URLs as defined in the `servers` object of an OpenAPI specification. This allows you to define API server URLs with templated variables (e.g., `https://{instance_id}.api.example.com/v1` or `https://api.example.com/{region}/users`).
-
-### Variable Resolution
-
-When an operation requires a server URL with variables, Arazzo Runner resolves these variables in the following order of precedence:
-
-1.  **Runtime Parameters**: Values passed explicitly when executing an operation or workflow (e.g., via the `--server-variables` CLI argument or the `runtime_params` parameter in `execute_operation`/`execute_workflow` methods). These parameters should be provided as a dictionary where keys match the expected environment variable names for the server variables (see below).
-2.  **Environment Variables**: If not provided as a runtime parameter, Arazzo Runner attempts to find an environment variable.
-3.  **Default Values**: If not found in runtime parameters or environment variables, the `default` value specified for the variable in the OpenAPI document's `servers` object is used.
-
-If a variable in the URL template cannot be resolved through any of these means, and it does not have a default value, an error will occur.
-
-### Environment Variable Naming
-
-The environment variables for server URLs follow these naming conventions:
-
--   If the OpenAPI specification's `info.title` is available and an `API_TITLE_PREFIX` can be derived from it (typically the first word of the title, uppercased and sanitized, e.g., `PETSTORE` from "Petstore API"), the format is:
-    `[API_TITLE_PREFIX_]RUNNER_SERVER_<VAR_NAME_UPPERCASE>`
-    Example: `PETSTORE_RUNNER_SERVER_REGION=us-east-1`
-
--   If an `API_TITLE_PREFIX` cannot be derived (e.g., `info.title` is missing or empty), the format is:
-    `RUNNER_SERVER_<VAR_NAME_UPPERCASE>`
-    Example: `RUNNER_SERVER_INSTANCE_ID=my-instance-123`
-
-The `<VAR_NAME_UPPERCASE>` corresponds to the variable name defined in the `servers` object's `variables` map (e.g., `region` or `instance_id`), converted to uppercase.
-
-You can use the `show-env-mappings` CLI command to see the expected environment variable names for server URLs, alongside authentication variables, for a given OpenAPI specification.
-
-### Example
-
-Consider an OpenAPI specification with:
-- `info.title: "My Custom API"`
-- A server definition:
-  ```yaml
-  servers:
-    - url: "https://{instance}.api.example.com/{version}"
-      variables:
-        instance:
-          default: "prod"
-          description: "The API instance name."
-        version:
-          default: "v1"
-          description: "API version."
-  ```
-
-To set the `instance` to "dev" and `version` to "v2" via environment variables, you would set:
-```sh
-export MYCUSTOM_RUNNER_SERVER_INSTANCE=dev
-export MYCUSTOM_RUNNER_SERVER_VERSION=v2
-```
-(Assuming "MYCUSTOM" is derived from "My Custom API").
-
-Alternatively, to provide these at runtime via the CLI when executing an operation:
-```sh
-uvx arazzo-runner execute-operation --openapi-path path/to/spec.yaml --operation-id someOperation \
-  --server-variables '{"MYCUSTOM_RUNNER_SERVER_INSTANCE": "staging", "MYCUSTOM_RUNNER_SERVER_VERSION": "v2beta"}'
-```
-
-
-## Overview
-
-Arazzo Runner orchestrates API workflows by:
-
-- Loading and validating Arazzo workflow documents
-- Executing workflow steps sequentially or conditionally
-- Evaluating runtime expressions and success criteria
-- Extracting and transforming data between steps
-- Handling flow control (continue, goto, retry, end)
-- Supporting nested workflow execution
-- Providing event callbacks for workflow lifecycle events
-- Managing authentication requirements across different APIs
-
-
-## Testing
-
-The Arazzo Runner includes a comprehensive testing framework for workflow validation:
-
-- Automated test fixtures for different workflow scenarios
-- Mock HTTP responses based on OpenAPI specs
-- Custom mock responses for specific endpoints
-- Validation of workflow outputs and API call counts
-
-For details on testing, see [Arazzo Runner Testing Framework](https://github.com/jentic/arazzo-engine/blob/main/runner/tests/README.md)
-
-## Arazzo Format
-
-The Arazzo specification is our workflow definition format that orchestrates API calls using OpenAPI specifications.
-
-- Schema: [arazzo-schema.yaml](https://github.com/jentic/arazzo-engine/blob/main/runner/arazzo_spec/arazzo-schema.yaml)
-- Documentation: [arazzo-spec.md](https://github.com/jentic/arazzo-engine/blob/main/runner/arazzo_spec/arazzo-spec.md)
diff --git a/runner/README.md b/runner/README.md
