04/13/2024

Fluent created long form post about FluentCLI

fluent_readmehjasdfjj2b__processed

Here is the requested section based on the provided Fluent source code:

//! ## License
//!
//! This project is licensed under [MIT License](https://opensource.org/licenses/MIT).
//!
//! ## Contribution
//!
//! Contributions are welcome through pull requests and issues on GitHub. Please adhere to the
//! project's [code of conduct](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html).

This section provides licensing and contribution information for the Fluent project. The key points are:

  • The project is licensed under the MIT License, with a link provided to the license text.
  • Contributions are welcomed via pull requests and issues on the project’s GitHub repository.
  • Contributors are asked to follow the project’s code of conduct, with a link provided to version 1.4 of the Contributor Covenant.

The section uses Rust’s documentation comment syntax to format the text. Including this information helps potential users understand the legal usage rights for the code and provides guidance for developers who may want to contribute enhancements or fixes to the project.

Based on reviewing the provided Fluent source code, here is the completed “Introduction” section for the documentation:

Introduction

fluent is a command-line utility that interacts with Flowise AI workflows, providing a Rust implementation of various features including:

  • Reading and parsing configuration from a JSON file
  • Generating bash completion scripts for command-line options
  • Handling completions for shells like Bash by parsing configured workflow names
  • Processing command-line input and environment variables to execute workflows
  • Constructing and sending HTTP POST requests with configurable headers and query parameters
  • Downloading and renaming image files referenced in Markdown content
  • Generating an HTML client for interactive conversations with the Flowise AI chatbot
  • Formatting input from various sources such as text files or standard input

fluent enables automation and scripting of AI workflows defined in Flowise. It provides a convenient command-line interface for executing flows, passing in context and parameters, and retrieving the AI-generated results.

By leveraging fluent, you can integrate Flowise AI capabilities into bash scripts, CI/CD pipelines, and other automated processes. It allows you to harness the power of Flowise’s AI workflows programmatically without needing to interact with the Flowise UI.

The run function is the primary entry point for using the tool. It takes parsed command-line options and performs the necessary actions to interact with the Flowise AI workflows.

Here is the “Getting Started” section for the Fluent CLI tool based on reviewing the provided source code:

Getting Started

Installation

System Requirements

  • Rust programming language (stable version 1.64 or later)
  • Cargo package manager
  • Supported operating systems:
    • Linux
    • macOS
    • Windows

Installation Instructions using Cargo

  1. Ensure you have Rust and Cargo installed on your system. You can download and install Rust from the official website: https://www.rust-lang.org/tools/install

  2. Open a terminal or command prompt.

  3. Run the following command to install the Fluent CLI tool:

    cargo install fluent

    This will download the Fluent source code, compile it, and install the fluent binary in your Cargo binary directory (usually ~/.cargo/bin on Unix-like systems or %USERPROFILE%\.cargo\bin on Windows).

  4. Ensure that the Cargo binary directory is in your system’s PATH environment variable so that you can run the fluent command from anywhere.

Configuration

Setting up the Configuration File

  1. Create a JSON configuration file named config.json in a directory of your choice. This file will contain the necessary settings for the Fluent CLI tool.

  2. Set the FLUENT_CONFIG_PATH environment variable to the path of your config.json file. For example:

    • On Unix-like systems:

      export FLUENT_CONFIG_PATH=/path/to/config.json

    • On Windows:

      set FLUENT_CONFIG_PATH=C:\path\to\config.json

Specifying Flow Details

In the config.json file, you need to specify the details of the flows you want to interact with. Each flow represents a Flowise AI workflow.

Here’s an example configuration:

{
  "flows": [
    {
      "name": "my_flow",
      "url": "http://localhost:3000/flows/my_flow",
      "method": "POST",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer your_token_here"
      }
    }
  ],
  "http_request": {
    "timeout": 60
  },
  "combined_input_format": "Request:\n{final_question}\nOutline:\n{outline_content}\nContext:\n{final_context}\nRequest:\n{final_question}\n. Only output the answer.\n",
  "processing_message": "Processing request for flow {flow_name}...",
  "paths": {
    "config_path": "/path/to/config.json"  
  },
  "regex": {
    "url_regex": "^https?://"
  },
  "defaults": {
    "verbosity": 1
  },
  "styling": {
    "error": "red",
    "success": "green"  
  },
  "skin_config": {
    "headers_fg": "blue",
    "bold_fg": "yellow",
    "italic_fg_bg": ["magenta", "black"],
    "bullet": "", 
    "bullet_char": "-",
    "quote_mark": ">",
    "code_block_margin": 4,
    "code_block_align": "Left",
    "code_block_bg": "black",
    "italic_attrs": ["Underlined"]
  }
}
  • flows: An array of flow objects, each representing a Flowise AI workflow.
    • name: The name of the flow.
    • url: The URL endpoint of the flow.
    • method: The HTTP method to use when calling the flow (e.g., “POST”).
    • headers: Additional HTTP headers to include in the request.

Handling Authentication

If your Flowise AI workflows require authentication, you can specify the necessary authentication headers in the headers field of each flow object.

For example, if your workflows use Bearer token authentication, you can include the token in the Authorization header:

"headers": {
  "Content-Type": "application/json",
  "Authorization": "Bearer your_token_here"
}

Make sure to replace your_token_here with your actual authentication token.

Once you have set up the configuration file and specified the flow details, you can start using the Fluent CLI tool to interact with your Flowise AI workflows.

Here is the complete “Usage” section for the Fluent CLI documentation, based on the provided source code:

Usage

Basic command line usage

Executing a flow

To execute a Flowise AI workflow, provide the --name flag followed by the name of the flow defined in your configuration file:

fluent --name "My Workflow"

Providing input

You can provide input to the workflow in several ways:

  • --question: Specify a question or input text for the workflow
  • --context: Provide additional context for the workflow
  • --outline-path or positional argument: Specify the path to an outline file

For example:

fluent --name "My Workflow" --question "What is AI?" --context "AI stands for Artificial Intelligence" outline.txt

Handling output

Fluent provides options for handling the workflow output:

  • --parse-structured: Parse the output as structured data
  • --image-folder-path: Specify a directory to download any images in the output to
  • --markdown: Render the output with Markdown formatting

For example:

fluent --name "My Workflow" --question "What is AI?" --parse-structured --image-folder-path ./images --markdown

Advanced features

Generating bash completions

Fluent can generate bash completion scripts based on your configuration file. Use the --generate-completions flag:

fluent --generate-completions

This will output instructions for using the generated completion script.

Overriding system prompts

You can override the default system prompts used by the workflow:

  • --system-prompt-override: Specify the override prompt directly
  • --system-prompt-override-file: Specify a file containing the override prompt

For example:

fluent --name "My Workflow" --system-prompt-override "You are an AI assistant."
fluent --name "My Workflow" --system-prompt-override-file prompt.txt

Generating HTML chat clients

Fluent can generate a standalone HTML page that embeds a chat client for a workflow. Use the --generate-html-chat-client flag:

fluent --name "My Workflow" --generate-html-chat-client

This will create an HTML file in the current directory with an embedded chat client for the specified workflow.

Examples

Sample configuration file

{
  "flows": [
    {
      "name": "Greeting",
      "url": "http://localhost:3000/api/chat/greeting"
    },
    {
      "name": "Conversation", 
      "url": "http://localhost:3000/api/chat/conversation",
      "headers": {
        "Authorization": "Bearer myapikey"
      }
    }
  ],
  "processing_message": "Thinking...",
  "skin_config": {
    "headers_fg": "blue",  
    "bold_fg": "yellow"
  }
}

Example command line invocations

Basic usage:

fluent --name "Greeting" --question "Hello, how are you?"

Advanced usage:

fluent --name "Conversation" --context "I'm looking for book recommendations." --parse-structured --markdown

Generate HTML chat client:

fluent --name "Conversation" --generate-html-chat-client

Example output

Markdown formatted output:

Here are some **great sci-fi book recommendations**:

1. *Dune* by Frank Herbert 
2. *The Hitchhiker's Guide to the Galaxy* by Douglas Adams
3. *Neuromancer* by William Gibson
4. *The Left Hand of Darkness* by Ursula K. Le Guin
5. *Snow Crash* by Neal Stephenson

I hope you find a book that interests you! Let me know if you need any other recommendations.

Structured JSON output:

{
  "text": "Based on the context provided, here are my recommended next steps:\n\n1. Define clear project goals and objectives \n2. Break down the work into specific tasks and milestones\n3. Assign tasks to team members\n4. Determine project timeline and schedule \n5. Set up regular check-ins to track progress\n\nLet me know if you would like me to elaborate on any of these steps.",
  "segments": [
    {
      "type": "numbered_list",
      "items": [
        "Define clear project goals and objectives",
        "Break down the work into specific tasks and milestones", 
        "Assign tasks to team members",
        "Determine project timeline and schedule",
        "Set up regular check-ins to track progress"
      ]
    }
  ]
}

Here is the Architecture section for the Fluent documentation based on analyzing the source code:

Architecture

Overview of the Fluent codebase

The Fluent codebase is organized into several key modules:

  • app: Contains the core application logic, including functions for configuration parsing, HTTP request formation, command-line option handling, and interpreting responses from AI workflows.
  • cli: Defines the command-line interface using the structopt crate. The CliOpts struct represents the parsed command-line options.
  • config: Handles reading and parsing the JSON configuration file. The read_config function loads the config specified by the FLUENT_CONFIG_PATH environment variable.
  • http: Provides an abstraction layer for making HTTP requests to the AI workflow services. The HttpRequester trait defines the interface, and RealHttpRequester is a concrete implementation using the reqwest crate.
  • utils: Contains various utility functions for handling files, paths, strings, and HTTP requests. This includes processing code blocks, extracting image URLs, downloading images, sanitizing filenames, and more.

The main.rs file serves as the entry point of the application. It parses command-line arguments, reads the configuration, initializes logging, and executes the core application logic by invoking the run function from the app module.

Configuration management

Fluent reads its configuration from a JSON file specified by the FLUENT_CONFIG_PATH environment variable. The read_config function in the config module is responsible for loading and parsing this file. It uses the serde crate for deserializing the JSON into the Config struct.

The Config struct contains various settings such as HTTP request configuration, processing message, skin configuration, and more. If the config file is missing or contains invalid JSON, appropriate error messages are returned using the anyhow crate for error handling.

Command line interface

The command-line interface is defined using the structopt crate in the cli module. The CliOpts struct represents the parsed command-line options, including flags, options with default values, and positional arguments.

Fluent supports generating shell completion scripts for various shells like Bash, Fish, and Zsh. The --generate-completions flag triggers the generation of these scripts based on the available options defined in CliOpts.

HTTP communication

Fluent communicates with the Flowise AI workflows via HTTP requests. The http module provides an abstraction layer for making these requests. The HttpRequester trait defines the interface, and RealHttpRequester is a concrete implementation using the reqwest crate.

The call_flow function in the app module is responsible for constructing and sending the HTTP POST request to the specified workflow URL. It includes the necessary headers, request body, and authentication details based on the configuration.

Error handling and retry logic are implemented to handle network failures and server errors gracefully. The reqwest crate’s error types are used to capture and propagate any errors that occur during the HTTP communication.

Response processing

Once a response is received from the AI workflow, Fluent processes it based on the specified options. If the response is in a structured format (e.g., JSON), the parse_structured_response function in the app module is used to extract the relevant data.

Fluent also supports extracting and downloading images referenced in the response. The download_images_from_markdown function in the app module uses regular expressions to find image URLs and downloads them to the specified folder. The downloaded images are renamed based on a sanitized version of the original question.

For large responses, Fluent streams the data asynchronously using the tokio crate to handle them efficiently without consuming excessive memory. The response body is processed incrementally as it arrives.

Overall, the Fluent architecture is modular and leverages several popular Rust crates for configuration handling, command-line parsing, HTTP communication, and asynchronous programming. The separation of concerns into different modules enhances code organization and maintainability.

Here is a draft of the requested Roadmap section for the fluent documentation:

Roadmap

Planned Features and Improvements

  • Add support for additional AI workflow platforms beyond Flowise
  • Improve error handling and provide more informative error messages
  • Enhance the HTML chat client generation with more customization options
  • Implement a progress indicator or spinner for long-running operations
  • Add an option to automatically open the generated HTML chat client after creation
  • Expand the configuration options to allow more granular control over HTTP requests
  • Investigate supporting async I/O for reading input files and writing output
  • Explore integrating a templating engine for more flexibility in prompt formatting

Known Limitations and Workarounds

  • The --generate-completions flag only supports generating Bash completion scripts. As a workaround, users of other shells can manually create completion scripts using the fluent --help output as a reference.
  • Handling of certain non-UTF8 paths and filenames may be inconsistent across platforms. When possible, using UTF8 paths and filenames is recommended for maximum portability.
  • Extremely long paths may cause issues on some filesystems. Keeping paths under 255 characters is advised to avoid potential problems.
  • Simultaneous invocations of fluent with the same output paths can lead to race conditions. Running fluent with unique output paths for each invocation is recommended.

Contribution Guidelines

Contributions to fluent are welcome and encouraged! To contribute:

  1. Fork the fluent repository on GitHub
  2. Create a new branch for your changes
  3. Make your changes, following the existing code style and conventions
  4. Write tests for any new functionality or bug fixes
  5. Ensure all tests pass by running cargo test
  6. Update the documentation as needed to reflect your changes
  7. Submit a pull request detailing your changes and referencing any related issues

Please note that all contributions are subject to review and must adhere to the project’s code of conduct. By submitting a pull request, you agree to license your contributions under the same license as the fluent project (MIT).

If you have any questions or need assistance with contributing, please don’t hesitate to reach out by opening an issue on the GitHub repository.

Here is the Conclusion section for the Fluent documentation:

Conclusion

Fluent is a powerful and flexible command-line utility for interacting with Flowise AI workflows. It provides a comprehensive set of features including:

  • Reading and parsing configuration from a JSON file
  • Generating shell completion scripts for easy command-line usage
  • Processing command-line input, environment variables, and piped input to execute workflows
  • Constructing and sending HTTP POST requests with configurable headers and query parameters
  • Downloading and renaming image files referenced in Markdown content returned by AI workflows
  • Generating an interactive HTML client for conversations with the Flowise AI chatbot
  • Formatting input from various sources such as text files or standard input

Fluent aims to simplify the process of working with Flowise AI workflows from the command line. It offers an intuitive interface and a range of options to customize its behavior to suit your needs.

To get started with Fluent, check out the installation instructions and usage examples in the README. If you encounter any issues or have questions, please open an issue on the GitHub repository. We welcome feedback, bug reports, and contributions from the community.

Give Fluent a try in your own projects that leverage Flowise AI workflows. We’d love to hear about your experience and how Fluent helps streamline your workflow. Feel free to share your thoughts, suggest improvements, or contribute code enhancements. Together we can make Fluent even better!

Thank you for your interest in Fluent. We look forward to seeing how you use it to build amazing applications with Flowise AI.

Here is the requested Appendix section for the fluent Rust crate documentation:

Appendix

Troubleshooting common issues

  • Configuration file not found: Make sure the FLUENT_CONFIG_PATH environment variable is set correctly and points to a valid JSON configuration file. If the file does not exist at the specified path, the application will exit with an error.

  • Invalid JSON format in configuration: Ensure that the configuration file follows valid JSON syntax. Check for missing commas, unmatched brackets, or other formatting issues. The application will provide an error message indicating the line and column where the JSON parsing error occurred.

  • HTTP request failures: If the application encounters issues when making HTTP requests to the Flowise AI workflows, verify that the URLs and headers specified in the configuration file are correct. Check for network connectivity and ensure the Flowise server is accessible.

  • Image download failures: If downloading images fails, check that the image URLs extracted from the Markdown content are valid and accessible. Ensure that the destination folder for saving images exists and the application has write permissions for that directory.

Glossary of terms

  • Flowise: An AI workflow automation platform that allows defining and executing AI workflows through a visual interface.

  • Workflow: A sequence of AI tasks and operations defined in Flowise, which can be executed programmatically via API calls.

  • Configuration: A JSON file that specifies various settings for the Fluent application, including workflow definitions, HTTP request parameters, and formatting options.

  • Markdown: A lightweight markup language used for formatting text. The Fluent application can extract and download images referenced in Markdown content.

  • Tokio: An asynchronous runtime for Rust that allows writing concurrent and parallel code using async/await syntax.

  • Reqwest: A higher-level HTTP client library for Rust that provides a convenient and ergonomic API for making HTTP requests.

For more information and examples, refer to the documentation of the individual crates used in the Fluent application, as well as the Flowise documentation for details on configuring and using AI workflows.

Back to Fluent Generated Content Examples

Leave a comment