openai-md

(OpenAI Markdown Generator)

A Typescript package/Node.js command-line tool that uses the OpenAI GPT-3 API to generate content in the form of markdown files.

Installation and usage

Command-line use

1. Install: From the terminal, run npm install -g openai-md.
2. API key: A valid OpenAI API key is necessary to run this app. There are two basic ways to enter your API key when running it as a command-line tool:

• You can enter your API key on the command-line, when prompted by the app.
• You can set an environment variable named OPENAI_API_KEY. There are several ways to do this:
  • Set it directly on the command-line with export OPENAI_API_KEY=<your key>.
  • Add it as a variable, to a local .env file and then run source <path/to/.env>. (This only works if the .env file is formatted correctly, without any spaces around the = sign, and with quotes around the value if the value contains spaces.)
  • Add it to your .bash_profile or .bashrc file.

3. Start: Run openai-md.

• With positional command-line arguments: openai-md "<prompt>" <temperature> <output directory> <filename>.
• With flags:
  • -p or --prompt The prompt to use when generating content.
  • -t or --temperature The temperature to use when generating content. (Default: 1.0)
  • -o or --output-directory The directory in which to save the generated markdown file. (Default: ./temp/)
  • -f or --filename The name of the generated markdown file. If no filename is provided, the app will select a filename. By default, if a title is to be added to the front matter, the filename will be generated from the title. Otherwise, if a date is included in the front matter, the date will be used as a filename. If neither title nor date appear in the front matter, or there is no front matter, the current date will be used (in the format YYYY-MM-DD).
  • -k or --api-key The API key to use when generating content.
  • -a or --author The author name to use in the "front matter" of the generated markdown file. Can also be included in the "meta data" JSON object.
  • -g or --front-matter-keys-to-generate Front matter keys for which you want the app to generate values. Enter as a comma-separated list, like "title, description, tags". Be sure to enclose the list in quotes.
  • -m or --meta Meta data to be added to the "front matter" of the generated markdown file. These values will override any values generated by the app. Enter as a JSON object, like "{\"testkey\": \"testvalue\"}". This value will be parsed as JSON, so be sure to escape any quotes. Be sure to enclose the JSON object in quotes. Given all of this, the command to use this flag would look like this: --meta="{\"testkey\": \"testvalue\"}". It is probably easier to enter this value when prompted by the app, instead of as a command-line argument, because you won't need to enclose the value in quotes, nor escape the inner quotes.
  • --help Display help information.
• You may enter a combination of positional arguments and flags. If you do, the positional arguments will be used first, and then the flags will be used to override any values that were entered as positional arguments. Example: openai-md "some prompt" 1.0 ./output_dir/ some-filename -a "Author Name" -g "title, description, tags" -m "{\"testkey\": \"testvalue\"}"

4. The app will prompt you for any of the following information not already entered as arguments (Default values will be displayed in brackets. You can just hit enter to accept the default value):

• Prompt: The prompt to use when generating content.
• OpenAI API key: The API key to use when generating content.
• Author: The author name to use in the "front matter" of the generated markdown file. Can also be included in the "meta data" JSON object.
• Front matter keys to generate: Front matter keys for which you want the app to generate values. Enter as a comma-separated list, like title, description, tags.
• Meta data to be added to front matter directly: Meta data to be added to the "front matter" of the generated markdown file. These values will override any values generated by the app. Enter as a JSON object, like {"testkey": "testvalue"}. Remember to enclose the keys in quotes. If no front matter keys are generated, and no meta data is provided, the app will not generate any front matter.
• Temperature: The temperature to use when generating content. (Default: 1.0)
• Output directory: The directory in which to save the generated markdown file. (Default: ./temp/)
• Filename: The name of the generated markdown file. If no filename is provided, the app will select a filename. By default, if a title is to be added to the front matter, the filename will be generated from the title. Otherwise, if a date is included in the front matter, the date will be used as a filename. If neither title nor date appear in the front matter, or there is no front matter, the current date will be used (in the format YYYY-MM-DD). If a filename is provided, the app will use that filename, and will not generate a title or date.

Programmatic use

1. Install: Run npm install --save openai-md, from the root directory of your project.

2. API key: A valid OpenAI API key is necessary to run this module. You can either set it as an environment variable (OPENAI_API_KEY), or pass it as an argument to the imported method.

3. Import: Import the desired methods from the module:

   import { generateMarkdown, generateMarkdownAndSaveToFile } from "openai-md";
   
   const prompt = "Write a post about Star Wars";
   
   // generate a markdown file as a text string
   const markdownString = await generateMarkdown(prompt);
   // -or-
   // generate a markdown file and save it to disk
   await generateMarkdownAndSaveToFile(prompt, {
     outputDirectory: "blog_posts",
     filename: "my-post",
     frontMatterToGenerate: ["title", "description", "tags"],
   });
   

Exported methods

• generateMarkdown(prompt, options): Generates a markdown file as a string. Parameters:
  • prompt (required) - The prompt to use when generating content.
  • options (optional) - An object that may have any or all of the following keys:
    • apiKey - The OpenAI API key to use when generating content. If not provided, the app will look for an environment variable named OPENAI_API_KEY. (If calling more than one method, it is only necessary to provide the API key with the first method call.)
    • meta - An object with meta data to be added to the "front matter" of the generated markdown file. These values will override any values generated by the app. For example, you could add an author and a date this way: {author: "Kilgore Trout", date: "1973-01-27"}.
    • frontMatterToGenerate - An array of front matter keys (strings) for which you want the app to generate values. For instance, if you want the app to generate a title, description, and tags, you would pass ["title", "description", "tags"]. If no front matter keys are generated, and no meta data is provided, the resulting markdown will not contain any front matter.
    • temperature - The temperature to use when generating content. (Default: 0.95)
    • model - The model to use when generating content. If you change this setting, you should probably also set the modelTokenLimit appropriately. (Default: gpt-3.5-turbo-0613)
    • modelTokenLimit - The token limit associated with the selected model. (Default: 4096)
    • minCompletionTokens - The minimum number of tokens to allow for a completion. (Default: 1028)
    • maxCompletionTokens - The maximum number of tokens to allow for a completion. (Default: 2048)
• generateMarkdownAndSaveToFile(prompt, options): Generates a markdown file and saves it to a file. Parameters:
  • prompt (required) - The prompt to use when generating content.
  • options (optional) - An object that may have any or all of the following keys:
    • apiKey - The OpenAI API key to use when generating content. If not provided, the app will look for an environment variable named OPENAI_API_KEY. (If calling more than one method, it is only necessary to provide the API key with the first method call.)
    • meta - An object with meta data to be added to the "front matter" of the generated markdown file. These values will override any values generated by the app. For example, you could add an author and a date this way: {author: "Kilgore Trout", date: "1973-01-27"}.
    • frontMatterToGenerate - An array of front matter keys (strings) for which you want the app to generate values. For instance, if you want the app to generate a title, description, and tags, you would pass ["title", "description", "tags"]. If no front matter keys are generated, and no meta data is provided, the resulting markdown will not contain any front matter.
    • temperature - The temperature to use when generating content. (Default: 0.95)
    • model - The model to use when generating content. If you change this setting, you should probably also set the modelTokenLimit appropriately. (Default: gpt-3.5-turbo-0613)
    • modelTokenLimit - The token limit associated with the selected model. (Default: 4096)
    • minCompletionTokens - The minimum number of tokens to allow for a completion. (Default: 1028)
    • maxCompletionTokens - The maximum number of tokens to allow for a completion. (Default: 2048)
    • outputDirectory - The directory in which to save the generated markdown file. (Default: ./temp/)
    • filename - The name of the generated markdown file. If no filename is provided, the app will select a filename. By default, if a title is to be added to the front matter, the filename will be generated from the title. Otherwise, if a date is included in the front matter, the date will be used as a filename. If neither title nor date appear in the front matter, or there is no front matter, the current date will be used (in the format YYYY-MM-DD).
    • filenameKey - The key to use when generating a filename from the front matter. Will not be used if a filename is passed. (Default: title)
• getModeration(prompt, apiKey): Gets the moderation status of a given prompt, including scores. Parameters:
  • prompt (required) - The prompt to apply moderation to.
  • apiKey (optional) - The OpenAI API key to use when generating content. If not provided, the app will look for an environment variable named OPENAI_API_KEY.
• failsModeration(prompt, apiKey): Checks if a given prompt fails moderation. Returns a string with the reason for failure, or false if the prompt passes moderation. Parameters:
  • prompt (required) - The prompt to apply moderation to.
  • apiKey (optional) - The OpenAI API key to use when generating content. If not provided, the app will look for an environment variable named OPENAI_API_KEY. (If calling more than one method, it is only necessary to provide the API key with the first method call.)
• getCompletion(prompt, options): Requests a completion from the OpenAI API for a given prompt. Will not apply any additional processing to the user prompt or the completion. Parameters:
  • prompt (required) - The prompt to use when generating content.
  • options (optional) - An object that may have any or all of the following keys:
    • apiKey - The OpenAI API key to use when generating content. If not provided, the app will look for an environment variable named OPENAI_API_KEY. (If calling more than one method, it is only necessary to provide the API key with the first method call.)
    • temperature - The temperature to use when generating content. (Default: 1.0)
    • model - The model to use when generating content. It is not recommended to change this setting. (Default: text-davinci-003)
    • maxTokens - The maximum number of tokens to generate. By default, will be set to 2048 - <estimated number of tokens in prompt>. It is not recommended to change this setting. (Max: 2048 )

License

Copyright © 2023, Dennis Hodges

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Source: http://opensource.org/licenses/ISC