Update getting started guide (guardrails-ai#629)

* update getting started guide

* update index

* update contributing guide

* making index work with docusaurus

* making images work

* img update

* fix docs index images

* use docusuarus img zoom plugin

* delete static files

* update contrbuting guide

* update completions to chat completions

---------

Co-authored-by: Zayd Simjee <[email protected]>

Author: ShreyaR

CONTRIBUTING.md

@@ -39,13 +39,16 @@ Thank you for your contribution and happy coding!
 
 ## Documentation
 
-Docs are served via mkdocs using the mkdocstring plugin. To serve docs locally, run the following
+Docs are served via docusaurus. To serve docs locally, run the following
 
 ```bash
 # install dependencies
-pip install -e ".[dev]";
+pip install -e ".[dev]"
 
-# serve docs
-mkdocs serve;
+# install npm dependencies
+npm i
+
+# serve the docs
+npm run start
 ```
-then navigate to `localhost:8000` in your browser.
+then navigate to `localhost:3000` in your browser.

docs/getting_started.ipynb renamed to docs-graveyard/getting_started.ipynb

@@ -0,0 +1,103 @@
+# Getting Started
+
+## Installation
+
+```python
+pip install guardrails-ai
+```
+
+## Create Input and Output Guards for LLM Validation
+
+1. Download and configure the Guardrails Hub CLI.
+    
+    ```bash
+    pip install guardrails-ai
+    guardrails configure
+    ```
+2. Install a guardrail from Guardrails Hub.
+
+    ```bash
+    gudardrails hub install hub://guardrails/regex_match
+    ```
+3. Create a Guard from the installed guardrail.
+
+    ```python
+    # Import Guard and Validator
+    from guardrails.hub import RegexMatch
+    from guardrails import Guard
+
+    # Initialize the Guard with 
+    val = Guard().use(
+        RegexMatch(regex="^[A-Z][a-z]*$")
+    )
+
+    guard.parse("Caesar")  # Guardrail Passes
+    guard.parse("Caesar is a great leader")  # Guardrail Fails
+    ```
+4. Run multiple guardrails within a Guard.
+    First, install the necessary guardrails from Guardrails Hub.
+
+    ```bash
+    guardrails hub install hub://guardrails/competitor_check
+    guardrails hub install hub://guardrails/toxic_language
+    ```
+
+    Then, create a Guard from the installed guardrails.
+    
+    ```python
+    from guardrails.hub import RegexMatch, ValidLength
+    from guardrails import Guard
+
+    guard = Guard().use(
+        RegexMatch(regex="^[A-Z][a-z]*$"),
+        ValidLength(min=1, max=32)
+    )
+
+    guard.parse("Caesar")  # Guardrail Passes
+    guard.parse("Caesar is a great leader")  # Guardrail Fails
+    ```
+
+
+## Use Guardrails to generate structured data from LLMs
+
+
+Let's go through an example where we ask an LLM to generate fake pet names. To do this, we'll create a Pydantic [BaseModel](https://docs.pydantic.dev/latest/api/base_model/) that represents the structure of the output we want.
+
+```py
+from pydantic import BaseModel, Field
+
+class Pet(BaseModel):
+    pet_type: str = Field(description="Species of pet")
+    name: str = Field(description="a unique pet name")
+```
+
+Now, create a Guard from the `Pet` class. The Guard can be used to call the LLM in a manner so that the output is formatted to the `Pet` class. Under the hood, this is done by either of two methods:
+1. Function calling: For LLMs that support function calling, we generate structured data using the function call syntax.
+2. Prompt optimization: For LLMs that don't support function calling, we add the schema of the expected output to the prompt so that the LLM can generate structured data.
+
+```py
+from guardrails import Guard
+import openai
+
+prompt = """
+    What kind of pet should I get and what should I name it?
+
+    ${gr.complete_json_suffix_v2}
+"""
+guard = Guard.from_pydantic(output_class=Pet, prompt=prompt)
+
+validated_output, *rest = guard(
+    llm_api=openai.completions.create,
+    engine="gpt-3.5-turbo-instruct"
+)
+
+print(f"{validated_output}")
+```
+
+This prints: 
+```
+{
+    "pet_type": "dog",
+    "name": "Buddy
+}
+```

docs-graveyard/getting_started.md

@@ -0,0 +1,103 @@
+# Getting Started
+
+## Installation
+
+```python
+pip install guardrails-ai
+```
+
+## Create Input and Output Guards for LLM Validation
+
+1. Download and configure the Guardrails Hub CLI.
+    
+    ```bash
+    pip install guardrails-ai
+    guardrails configure
+    ```
+2. Install a guardrail from Guardrails Hub.
+
+    ```bash
+    gudardrails hub install hub://guardrails/regex_match
+    ```
+3. Create a Guard from the installed guardrail.
+
+    ```python
+    # Import Guard and Validator
+    from guardrails.hub import RegexMatch
+    from guardrails import Guard
+
+    # Initialize the Guard with 
+    val = Guard().use(
+        RegexMatch(regex="^[A-Z][a-z]*$")
+    )
+
+    guard.parse("Caesar")  # Guardrail Passes
+    guard.parse("Caesar is a great leader")  # Guardrail Fails
+    ```
+4. Run multiple guardrails within a Guard.
+    First, install the necessary guardrails from Guardrails Hub.
+
+    ```bash
+    guardrails hub install hub://guardrails/competitor_check
+    guardrails hub install hub://guardrails/toxic_language
+    ```
+
+    Then, create a Guard from the installed guardrails.
+    
+    ```python
+    from guardrails.hub import RegexMatch, ValidLength
+    from guardrails import Guard
+
+    guard = Guard().use(
+        RegexMatch(regex="^[A-Z][a-z]*$"),
+        ValidLength(min=1, max=32)
+    )
+
+    guard.parse("Caesar")  # Guardrail Passes
+    guard.parse("Caesar is a great leader")  # Guardrail Fails
+    ```
+
+
+## Use Guardrails to generate structured data from LLMs
+
+
+Let's go through an example where we ask an LLM to generate fake pet names. To do this, we'll create a Pydantic [BaseModel](https://docs.pydantic.dev/latest/api/base_model/) that represents the structure of the output we want.
+
+```py
+from pydantic import BaseModel, Field
+
+class Pet(BaseModel):
+    pet_type: str = Field(description="Species of pet")
+    name: str = Field(description="a unique pet name")
+```
+
+Now, create a Guard from the `Pet` class. The Guard can be used to call the LLM in a manner so that the output is formatted to the `Pet` class. Under the hood, this is done by either of two methods:
+1. Function calling: For LLMs that support function calling, we generate structured data using the function call syntax.
+2. Prompt optimization: For LLMs that don't support function calling, we add the schema of the expected output to the prompt so that the LLM can generate structured data.
+
+```py
+from guardrails import Guard
+import openai
+
+prompt = """
+    What kind of pet should I get and what should I name it?
+
+    ${gr.complete_json_suffix_v2}
+"""
+guard = Guard.from_pydantic(output_class=Pet, prompt=prompt)
+
+validated_output, *rest = guard(
+    llm_api=openai.chat.completions.create,
+    engine="gpt-3.5-turbo"
+)
+
+print(f"{validated_output}")
+```
+
+This prints: 
+```
+{
+    "pet_type": "dog",
+    "name": "Buddy
+}
+```

docs/guardrails_ai/getting_started.ipynb renamed to docs-graveyard/guardrails_ai/getting_started.ipynb

@@ -1,42 +1,20 @@
 # Guardrails AI
 
-## 🛤️ What is Guardrails AI?
+## What is Guardrails?
 
-Guardrails AI is the leading open-source framework to define and enforce assurance for LLM applications. It offers
+Guardrails is a Python framework that helps build reliable AI applications by performing two key functions:
+1. Guardrails runs Input/Output Guards in your application that detect, quantify and mitigate the presence of specific types of risks. To look at the full suite of risks, check out [Guardrails Hub](https://hub.guardrailsai.com/).
+2. Guardrails help you generate structured data from LLMs.
 
-✅ Framework for creating custom validations at an application level
 
-✅ Orchestration of prompting → verification → re-prompting
+<div align="center">
+<img src="https://raw.githubusercontent.com/guardrails-ai/guardrails/main/docs/img/with_and_without_guardrails.svg" alt="Guardrails in your application" width="1500px" />
+</div>
 
-✅ Library of commonly used validators for multiple use cases
+### Guardrails Hub
 
-✅ Specification language for communicating requirements to LLM
+Guardrails Hub is a collection of pre-built measures of specific types of risks (called 'validators'). Multiple validators can be combined together into Input and Output Guards that intercept the inputs and outputs of LLMs. Visit [Guardrails Hub](https://hub.guardrailsai.com/) to see the full list of validators and their documentation.
 
-## 🚒 Under the hood
-
-Guardrails provides an object definition called a `Rail` for enforcing a specification on an LLM output, and a lightweight wrapper called a `Guard` around LLM API calls to implement this spec.
-
-1. `rail` (**R**eliable **AI** markup **L**anguage) files for specifying structure and type information, validators and corrective actions over LLM outputs. The concept of a Rail has evolved from markup - Rails can be defined in either <a href='/docs-graveyard/defining_guards/pydantic.ipynb'>Pydantic</a> or <a href='/docs/how_to_guides/rail'>RAIL</a> for structured outputs, or directly in <a href='/docs-graveyard/defining_guards/strings.ipynb'>Python</a> for string outputs.
-2. `Guard` wraps around LLM API calls to structure, validate and correct the outputs.
-
-```mermaid
-graph LR
-    A[Create `RAIL` spec] --> B["Initialize `guard` from spec"];
-    B --> C["Wrap LLM API call with `guard`"];
-```
-
-Check out the [Getting Started](/docs/guardrails_ai/getting_started) guide to learn how to use Guardrails.
-
-## 📍 Roadmap
-
-- [ ] Javascript SDK
-- [ ] Wider variety of language support (TypeScript, Go, etc)
-- [ ] Informative logging
-- [ ] VSCode extension for `.rail` files
-- [ ] Next version of `.rail` format
-- [ ] Validator playground
-- [x] Input Validation
-- [x] Pydantic 2.0
-- [x] Improving reasking logic
-- [x] Integration with LangChain
-- [x] Add more LLM providers
+<div align="center">
+<img src="https://raw.githubusercontent.com/guardrails-ai/guardrails/main/docs/img/guardrails_hub.gif" alt="Guardrails Hub gif" width="600px" />
+</div>

docs/guardrails_ai/getting_started.rail renamed to docs-graveyard/guardrails_ai/getting_started.rail

@@ -37,6 +37,9 @@ const config = {
     defaultLocale: "en",
     locales: ["en"],
   },
+  plugins: [
+    'docusaurus-plugin-image-zoom'
+  ],
   presets: [[
     "@docusaurus/preset-classic",
     /** @type {import('@docusaurus/preset-classic').Options} */
@@ -88,6 +91,19 @@ const config = {
       footer: {
         copyright: `Copyright © ${new Date().getFullYear()} Guardrails AI`,
       },
+      zoom: {
+        // CSS selector to apply the plugin to, defaults to '.markdown img'
+        // selector: '.markdown img',
+        // Optional medium-zoom options
+        // see: https://www.npmjs.com/package/medium-zoom#options
+        options: {
+          margin: 24,
+          background: '#BADA55',
+          scrollOffset: 0,
+          container: '#zoom-container',
+          template: '#zoom-template',
+        },
+      },  
     }),
 };